System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 79147e6cea4277135d49ad87e7137e7765d0c6bb:


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 38 2e 32 22 0a 23 64 65 66 69 6e 65 20 53 51  .8.2".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 38 30 30 32 0a 23 64 65 66  BER 3008002.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33 2d  E_ID      "2013-
1070: 31 31 2d 30 38 20 32 30 3a 31 30 3a 35 37 20 66  11-08 20:10:57 f
1080: 62 66 38 63 33 38 32 38 33 32 37 64 31 39 62 62  bf8c3828327d19bb
1090: 63 65 30 64 37 66 36 37 33 35 65 37 35 37 37 61  ce0d7f6735e7577a
10a0: 62 66 64 35 34 62 33 22 0a 0a 2f 2a 0a 2a 2a 20  bfd54b3"../*.** 
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51  e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1c70: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
1c80: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
1c90: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1ca0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
1cb0: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
1cc0: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
1cd0: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
1ce0: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
1cf0: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
1d00: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
1d10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1d20: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1d30: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
1d40: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
1d50: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
1d60: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
1d70: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
1d80: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1d90: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
1da0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1db0: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1dc0: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1dd0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1de0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
1df0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
1e00: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
1e10: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
1e20: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
1e30: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
1e40: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
1e50: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
1e60: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
1e70: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
1e80: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
1e90: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
1ea0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
1eb0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
1ec0: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
1ed0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
1ee0: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1ef0: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
1f00: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
1f10: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
1f20: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1f30: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
1f40: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
1f50: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
1f60: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
1f70: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
1f80: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
1f90: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1fa0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
1fb0: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
1fc0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fd0: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
1fe0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
1ff0: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
2000: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2010: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
2020: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2030: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
2040: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2050: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2060: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
2070: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
2080: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
2090: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
20a0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
20b0: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
20c0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
20d0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
20f0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
2100: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2110: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
2120: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2130: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
2140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2150: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74  TEX].  ^(The ret
2160: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2170: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65  .** sqlite3_thre
2180: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
2190: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65  n shows only the
21a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65   compile-time se
21b0: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65  tting of.** thre
21c0: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61  ad safety, not a
21d0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
21e0: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74  ges to that sett
21f0: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73  ing made by.** s
2200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
2210: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2220: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2230: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74  e from sqlite3_t
2240: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69  hreadsafe().** i
2250: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63  s unchanged by c
2260: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2270: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a  config().)^.**.*
2280: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
2290: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
22a0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
22b0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
22c0: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
22d0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
22e0: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
22f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2300: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2310: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
2320: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
2330: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
2340: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2350: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
2360: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
2370: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
2380: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
2390: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
23a0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
23b0: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
23c0: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
23d0: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
23e0: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
23f0: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
2400: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
2410: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2420: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2430: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
2440: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2450: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
2460: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
2470: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
2480: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20  close()].** and 
2490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
24a0: 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73  2()] are its des
24b0: 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65  tructors.  There
24c0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a   are many other.
24d0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  ** interfaces (s
24e0: 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74  uch as.** [sqlit
24f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2500: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2510: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
2520: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2530: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
2540: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
2550: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
2560: 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ds on an.** sqli
2570: 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74  te3 object..*/.t
2580: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2590: 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a  lite3 sqlite3;..
25a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25b0: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
25c0: 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
25d0: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
25e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
25f0: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
2600: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
2610: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
2620: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
2630: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
2640: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
2650: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
2660: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
2670: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
2680: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2690: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
26a0: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
26b0: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
26c0: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
26d0: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
26e0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
26f0: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
2700: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
2710: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
2720: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
2730: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2740: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2750: 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  _int64 types can
2760: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
2770: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
2780: 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37   -92233720368547
2790: 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33  75808 and +92233
27a0: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69  72036854775807 i
27b0: 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a  nclusive.  ^The.
27c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  ** sqlite3_uint6
27d0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
27e0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
27f0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2800: 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  es .** between 0
2810: 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37   and +1844674407
2820: 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75  3709551615 inclu
2830: 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  sive..*/.#ifdef 
2840: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2850: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
2860: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
2870: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2880: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
2890: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28b0: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
28c0: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
28d0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
28e0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
28f0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
2900: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2910: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
2920: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
2930: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
2940: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2950: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2960: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
2970: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
2980: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
2990: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
29a0: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
29b0: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
29c0: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
29d0: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
29e0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
29f0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
2a00: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
2a10: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
2a20: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
2a30: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
2a40: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
2a50: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
2a60: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
2a70: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
2a80: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
2a90: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2aa0: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
2ab0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2ac0: 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
2ad0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2ae0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2af0: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2b00: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2b10: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2b20: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2b30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2b40: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2b50: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2b60: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
2b70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2b80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2b90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ba0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2bb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2bc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2bd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2be0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2bf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2c00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2c10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2c20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2c30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2c40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2c50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2c60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2c70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2c80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2c90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2ca0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2cb0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2cc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2cd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2ce0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cf0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69  ents.** and unfi
2d00: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2d10: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65  ackups, then the
2d20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d30: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20  tion becomes.** 
2d40: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d  an unusable "zom
2d50: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20  bie" which will 
2d60: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65  automatically be
2d70: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
2d80: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72  n the.** last pr
2d90: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2da0: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72   is finalized or
2db0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
2dc0: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66  3_backup is.** f
2dd0: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71  inished.  The sq
2de0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2df0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
2e00: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77  tended for use w
2e10: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67  ith.** host lang
2e20: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67  uages that are g
2e30: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64  arbage collected
2e40: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20  , and where the 
2e50: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a  order in which.*
2e60: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72  * destructors ar
2e70: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69  e called is arbi
2e80: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  trary..**.** App
2e90: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2eb0: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
2ec0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
2ed0: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71  tements],.** [sq
2ee0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2ef0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2f00: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
2f10: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  d .** [sqlite3_b
2f20: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66  ackup_finish | f
2f30: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69  inish] all [sqli
2f40: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2f50: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  cts associated.*
2f60: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
2f70: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
2f80: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20  r to attempting 
2f90: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a  to close the obj
2fa0: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c  ect.  ^If.** sql
2fb0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2fc0: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  is called on a [
2fd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fe0: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20  ion] that still 
2ff0: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69  has.** outstandi
3000: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ng [prepared sta
3010: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
3020: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72  handles], and/or
3030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3040: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65  kup] objects the
3050: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c  n it returns SQL
3060: 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64  ITE_OK but the d
3070: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3080: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3090: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
30a0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
30b0: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
30c0: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
30d0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30e0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
30f0: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3100: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3110: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3120: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3130: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
3140: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
3150: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3160: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3170: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3180: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3190: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
31a0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
31b0: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
31c0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
31d0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
31e0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
31f0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3200: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3210: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3220: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3230: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
3240: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
3250: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3260: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3270: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3280: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3290: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
32a0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
32b0: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
32c0: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
32d0: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
32e0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
32f0: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  se(sqlite3*);.SQ
3300: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
3310: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
3320: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
3330: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
3340: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3350: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
3360: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
3370: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
3380: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
3390: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
33a0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
33b0: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
33c0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
33d0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
33e0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
33f0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
3400: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
3410: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
3420: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
3430: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
3440: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3450: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
3460: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
3470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
3480: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
3490: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
34a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34b0: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
34c0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
34d0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
34e0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
34f0: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
3500: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
3510: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
3520: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
3530: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3540: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
3550: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
3560: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
3570: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
3580: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3590: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
35a0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
35b0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
35c0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35d0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
35e0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
35f0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
3600: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3610: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
3620: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3630: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3640: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3650: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
3660: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
3670: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
3680: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
3690: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
36a0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
36b0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
36c0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
36d0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
36e0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
36f0: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
3700: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
3710: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3720: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3740: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
3750: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
3760: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
3770: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
3780: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
3790: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
37a0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
37b0: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
37c0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
37d0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
37e0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
37f0: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
3800: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
3810: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
3820: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
3830: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
3840: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3850: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3860: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
3870: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
3880: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
3890: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
38a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
38b0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38c0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
38d0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
38e0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
38f0: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
3900: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
3910: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
3920: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
3930: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
3940: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
3950: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
3960: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
3970: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
3980: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
3990: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
39a0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
39b0: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
39c0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
39d0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
39e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
39f0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3a00: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3a10: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3a20: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3a30: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3a40: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
3a50: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
3a60: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
3a70: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
3a80: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3a90: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
3aa0: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3ab0: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3ac0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3ad0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3ae0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3af0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3b00: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3b10: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3b20: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3b30: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3b40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3b60: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3b70: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3b80: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3b90: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3ba0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3bb0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3bc0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3bd0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3be0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3bf0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3c00: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3c10: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3c20: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3c30: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3c40: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3c50: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3c60: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3c70: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3c80: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3c90: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3ca0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3cb0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3cc0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3cd0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3ce0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3cf0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3d00: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3d10: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3d20: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3d30: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3d40: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3d50: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3d60: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3d70: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3d80: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3d90: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3da0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3db0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3dc0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3dd0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3de0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3df0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3e00: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
3e10: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
3e20: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
3e30: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
3e40: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
3e50: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
3e60: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
3e70: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
3e80: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
3e90: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
3ea0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3eb0: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
3ec0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
3ef0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
3f00: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
3f10: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
3f20: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f30: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
3f40: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3f50: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3f60: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3f70: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f80: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f90: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3fa0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3fb0: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3fc0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3fd0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3fe0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3ff0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
4000: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
4010: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
4020: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
4040: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
4050: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
4060: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65   int sqlite3_exe
4070: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
40b0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
40c0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
40f0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
4100: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
4110: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
4120: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
4130: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
4140: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
4180: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
4190: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
41c0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
41d0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
41e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
41f0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4200: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
4210: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
4220: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
4250: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
4260: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
4270: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
4280: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
4290: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
42a0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
42b0: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20  der to indicate 
42c0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
42d0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
42e0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
42f0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
4300: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4310: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
4320: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
4330: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
4340: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
4350: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74  ,.** [sqlite3_vt
4360: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
4370: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  ] [SQLITE_ROLLBA
4380: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  CK | result code
4390: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s]..*/.#define S
43a0: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
43b0: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
43c0: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
43d0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
43e0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
43f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
4400: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
4410: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
4420: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
4430: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4440: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
4450: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
4460: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
4470: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
4480: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
4490: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
44a0: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
44b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
44c0: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
44d0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
44e0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
44f0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
4510: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
4520: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4530: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
4540: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4550: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
4560: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
4570: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
4580: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4590: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
45a0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
45b0: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
45e0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
45f0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
4600: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4620: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
4630: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
4640: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
4650: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4670: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
4680: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
4690: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
46a0: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
46b0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
46c0: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
46d0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
46e0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
4710: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
4720: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
4730: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
4760: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
4770: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
4780: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
47b0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
47c0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
47d0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
47e0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
47f0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
4800: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
4810: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
4830: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
4840: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4850: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4860: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4870: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4880: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4890: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
48a0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
48b0: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
48c0: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
48d0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
48f0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
4900: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
4910: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
4920: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
4930: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
4940: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4950: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4970: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4980: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4990: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
49a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
49b0: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
49c0: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
49d0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
49e0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
4a00: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
4a10: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
4a20: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4a30: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
4a40: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4a50: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4a60: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4a80: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4a90: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4aa0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4ab0: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4ad0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4ae0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
4af0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
4b00: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
4b20: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e  E      27   /* N
4b30: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f  otifications fro
4b40: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b60: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38  E_WARNING     28
4b70: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66     /* Warnings f
4b80: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4b90: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4ba0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4bb0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4bc0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4bd0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4bf0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4c00: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4c10: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4c20: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4c30: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4c40: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4c50: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4c60: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4c70: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4c80: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  ed error code} {
4c90: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4ca0: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
4cb0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
4cc0: 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ult code} {exten
4cd0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ce0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
4cf0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
4d00: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
4d10: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
4d20: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
4d30: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
4d40: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4d50: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4d60: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4d70: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4d80: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4d90: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4da0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4db0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4dc0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4dd0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4de0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4df0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e00: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e10: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e20: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e30: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e40: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4e50: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4e60: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4e70: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4e80: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4e90: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4ea0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4eb0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4ec0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
4ed0: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
4ee0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4ef0: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4f00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4f10: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4f20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4f30: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4f40: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20  s()] API..**.** 
4f50: 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69  Some of the avai
4f60: 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72  lable extended r
4f70: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4f80: 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20  listed here..** 
4f90: 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74  One may expect t
4fa0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
4fb0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4fc0: 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e  es will be expan
4fd0: 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20  d.** over time. 
4fe0: 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75   Software that u
4ff0: 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73  ses extended res
5000: 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64  ult codes should
5010: 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65   expect.** to se
5020: 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64  e new result cod
5030: 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  es in future rel
5040: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
5050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5060: 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65  E_OK result code
5070: 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65   will never be e
5080: 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c  xtended.  It wil
5090: 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65  l always.** be e
50a0: 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a  xactly zero..*/.
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50c0: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5100: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5120: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ERR | (2<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20  RR_WRITE        
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5180: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51a0: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20  _DIR_FSYNC      
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5200: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20  TRUNCATE        
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5220: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
5240: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20  STAT            
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5260: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
5280: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52a0: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
52c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5300: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53  TE            (S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5320: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5330: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
5340: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53  KED           (S
5350: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5360: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
5380: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  M             (S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53a0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
53b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45  QLITE_IOERR_ACCE
53c0: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53  SS            (S
53d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
53f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43  QLITE_IOERR_CHEC
5400: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53  KRESERVEDLOCK (S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5420: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b  QLITE_IOERR_LOCK
5440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5450: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5460: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5470: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53  QLITE_IOERR_CLOS
5480: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
5490: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
54a0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
54b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
54c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53  CLOSE         (S
54d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
54e0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
54f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f  QLITE_IOERR_SHMO
5500: 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53  PEN           (S
5510: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5520: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5530: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53  QLITE_IOERR_SHMS
5540: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53  IZE           (S
5550: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5560: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5570: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c  QLITE_IOERR_SHML
5580: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53  OCK           (S
5590: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
55a0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
55b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d  QLITE_IOERR_SHMM
55c0: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AP            (S
55d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
55e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
55f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b  QLITE_IOERR_SEEK
5600: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5610: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5620: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5630: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5640: 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53  TE_NOENT      (S
5650: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5660: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5670: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50  QLITE_IOERR_MMAP
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5690: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
56a0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
56b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54  QLITE_IOERR_GETT
56c0: 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53  EMPPATH       (S
56d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
56e0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
56f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56  QLITE_IOERR_CONV
5700: 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53  PATH          (S
5710: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5720: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5730: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41  QLITE_LOCKED_SHA
5740: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53  REDCACHE      (S
5750: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20  QLITE_LOCKED |  
5760: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5770: 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f  SQLITE_BUSY_RECO
5780: 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28  VERY           (
5790: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
57a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
57b0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41   SQLITE_BUSY_SNA
57c0: 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20  PSHOT           
57d0: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
57e0: 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (2<<8)).#defin
57f0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5800: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
5810: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5820: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
5830: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5840: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
5850: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5860: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
5870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5880: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
5890: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
58a0: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
58b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58c0: 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48  ANTOPEN_CONVPATH
58d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
58e0: 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29  ANTOPEN | (4<<8)
58f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5900: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
5910: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5920: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
5930: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5940: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5950: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5960: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
5970: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5980: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
5990: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
59a0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
59b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
59c0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
59d0: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53  OLLBACK       (S
59e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
59f0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5a00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a10: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a20: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a30: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5a40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a50: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5a60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a70: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a90: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5aa0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ab0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ad0: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5ae0: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5af0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b20: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b60: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5b70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b80: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5b90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ba0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5bb0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bc0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5be0: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5bf0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c30: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5c40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c50: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5c60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c70: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5c80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c90: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5cb0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5cc0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5cd0: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5cf0: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d00: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5d10: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5d20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d30: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5d40: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5d50: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5d70: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5d80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5d90: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5da0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5db0: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5dc0: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5dd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5de0: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5df0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5e00: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5e10: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5e20: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5e30: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5e40: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5e50: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5e60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5e70: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e90: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5ea0: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5eb0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5ec0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5ed0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ee0: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5ef0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5f00: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f10: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f30: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5f40: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5f50: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f60: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f80: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5f90: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5fa0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5fb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fc0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5fd0: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5fe0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ff0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6000: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
6010: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
6020: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6030: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6040: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
6050: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
6060: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6070: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6080: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6090: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
60a0: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
60b0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
60c0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
60d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
60e0: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
60f0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
6100: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6110: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6120: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
6130: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
6140: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6150: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6160: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
6170: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
6180: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6190: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
61a0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
61b0: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
61c0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
61d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
61e0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
61f0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
6200: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6210: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6220: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
6230: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
6240: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6250: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6260: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
6270: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
6280: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6290: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
62a0: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
62b0: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
62c0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
62d0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
62e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
62f0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
6300: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
6310: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6320: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6330: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6340: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
6350: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6360: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6370: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6380: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6390: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
63a0: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
63b0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
63c0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
63d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
63e0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
63f0: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
6400: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
6410: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6430: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
6440: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6450: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6460: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
6470: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6480: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6490: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
64a0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
64b0: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
64c0: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
64d0: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
64e0: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
64f0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
6500: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
6510: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
6520: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
6530: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
6540: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
6550: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6560: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
6570: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6580: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6590: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
65a0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
65b0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
65c0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
65d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
65e0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
65f0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
6600: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
6610: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
6620: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
6630: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
6640: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6650: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6660: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6670: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6680: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6690: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
66a0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
66b0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
66c0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
66d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
66e0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
66f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
6700: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
6710: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
6720: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
6730: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6740: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6750: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6760: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6770: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6780: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6790: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
67a0: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
67b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
67c0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
67d0: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
67e0: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
67f0: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
6800: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
6810: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
6820: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
6830: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
6840: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
6850: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6860: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
6870: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
6880: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6890: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
68a0: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
68b0: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
68c0: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
68d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
68e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
68f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6900: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
6910: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6920: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
6930: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6940: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6950: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6970: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6980: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6990: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
69a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
69b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
69d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69e0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
69f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a00: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
6a10: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
6a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a30: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6a40: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a50: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6a60: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6a70: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6a80: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6a90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6aa0: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6ab0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ac0: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6ad0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6ae0: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
6af0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
6b00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b10: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
6b20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
6b30: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b40: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6b50: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6b60: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6b70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6b80: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6b90: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6ba0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6bb0: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6bc0: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6bd0: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6be0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6bf0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6c00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
6c10: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
6c20: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
6c30: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
6c40: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6c50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6c60: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c80: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ca0: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6cb0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6cc0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6cd0: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6ce0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
6cf0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
6d00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6d10: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
6d20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6d30: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
6d40: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6d50: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6d60: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6d70: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6d80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6d90: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6da0: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6db0: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6dc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6dd0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6de0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6df0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6e00: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6e10: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6e20: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6e30: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6e40: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6e50: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6e60: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6e70: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6e80: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6e90: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6ea0: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6eb0: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6ec0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6ed0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6ee0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6ef0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6f00: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6f10: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6f20: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6f30: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6f40: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6f50: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6f60: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6f70: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6f80: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6f90: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6fa0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6fb0: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
6fc0: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
6fd0: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
6fe0: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
6ff0: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
7000: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
7010: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
7020: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
7030: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
7040: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
7050: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
7060: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
7070: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
7080: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
7090: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
70a0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
70b0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
70c0: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
70d0: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
70e0: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
70f0: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
7100: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
7110: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
7120: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
7130: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
7140: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
7150: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
7160: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7170: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
7180: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
7190: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
71a0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
71b0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
71c0: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
71d0: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
71e0: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
71f0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
7200: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
7210: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
7220: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
7230: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
7240: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7250: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
7260: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
7280: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
7290: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
72a0: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
72b0: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
72c0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
72d0: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
72e0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
72f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7300: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
7310: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
7320: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
7330: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
7340: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7350: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7360: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7370: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7380: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7390: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
73a0: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
73b0: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
73c0: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
73d0: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
73e0: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
73f0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
7400: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7410: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
7420: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
7430: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
7440: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7450: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7460: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7470: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7490: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
74a0: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
74b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
74c0: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
74d0: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
74e0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
74f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7500: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7510: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
7520: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
7530: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
7540: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7550: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7560: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7570: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
7580: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7590: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
75a0: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
75b0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
75c0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
75d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
75e0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
75f0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
7600: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7610: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
7620: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
7630: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
7640: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7650: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7660: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7670: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7680: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7690: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
76a0: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
76b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
76c0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
76d0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
76e0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
76f0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
7700: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
7710: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
7720: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
7730: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7740: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7750: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7760: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7770: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7780: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7790: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
77a0: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
77b0: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
77c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
77d0: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
77e0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
77f0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7800: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
7810: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
7820: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
7830: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
7840: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7850: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
7860: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
7870: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
7880: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7890: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
78a0: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
78b0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
78c0: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
78d0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
78e0: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
78f0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
7900: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
7910: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
7920: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
7930: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
7940: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
7950: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
7960: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
7970: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
7980: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7990: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
79a0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
79b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
79c0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
79d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
79e0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
79f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a00: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
7a10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7a20: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
7a30: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
7a40: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7a50: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7a60: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7a70: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7a80: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7a90: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7aa0: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7ab0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7ac0: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7ad0: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7ae0: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
7af0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
7b00: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
7b10: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
7b20: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
7b30: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
7b40: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7b50: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7b60: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7b70: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7b80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7b90: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7ba0: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7bb0: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7bc0: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7bd0: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7be0: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
7bf0: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
7c00: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7c10: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
7c20: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
7c30: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
7c40: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7c50: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7c60: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7c70: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7c80: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7c90: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7ca0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7cb0: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7cc0: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7cd0: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7ce0: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
7cf0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
7d00: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
7d10: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
7d20: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
7d30: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
7d40: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7d50: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7d60: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7d70: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7d80: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7d90: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7da0: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7db0: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7dc0: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7dd0: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7de0: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7df0: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7e00: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7e10: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7e20: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
7e30: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7e40: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
7e50: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
7e60: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
7e70: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
7e80: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
7e90: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
7ea0: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
7eb0: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
7ec0: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
7ed0: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
7ee0: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
7ef0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
7f00: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
7f10: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
7f20: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
7f30: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
7f40: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
7f50: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
7f60: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
7f70: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
7f80: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
7f90: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
7fa0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
7fb0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
7fc0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
7fd0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7fe0: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7ff0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
8000: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
8010: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
8020: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
8030: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
8040: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
8050: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
8060: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
8070: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
8080: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
8090: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
80a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
80b0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
80c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80d0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
80e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
80f0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
8120: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8130: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
8140: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8150: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
8160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8170: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
8180: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8190: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
81a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
81c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
81d0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
81e0: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
81f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
8200: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
8210: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
8220: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
8230: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
8240: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
8250: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
8260: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
8270: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
8280: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
8290: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
82a0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
82b0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
82c0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
82d0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
82e0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
82f0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
8300: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
8310: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
8320: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8330: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
8340: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8350: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8360: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
8370: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
8380: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8390: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
83a0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
83b0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
83c0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
83d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
83e0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
83f0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
8400: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
8410: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
8420: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
8430: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
8440: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8450: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8460: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
8470: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
8480: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8490: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
84a0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
84b0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
84c0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
84d0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
84e0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
84f0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
8500: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
8510: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
8520: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8530: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
8540: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8550: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8560: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8570: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8580: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8590: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
85a0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
85b0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
85c0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
85d0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
85e0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
85f0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
8600: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
8610: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
8620: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
8630: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
8640: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8650: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8660: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8670: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8680: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8690: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
86a0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
86b0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
86c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
86d0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
86e0: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
86f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8700: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
8710: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
8720: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8730: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
8740: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8750: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8760: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
8770: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
8780: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8790: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
87a0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
87b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
87c0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
87d0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
87e0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
87f0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
8800: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8810: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
8820: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
8830: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8840: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8850: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8860: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8870: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
8880: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8890: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
88a0: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
88b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
88c0: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
88d0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
88e0: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
88f0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
8900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
8910: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
8920: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
8930: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
8940: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8950: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8960: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
8970: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8980: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8990: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
89a0: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
89b0: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
89c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
89d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
89e0: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
89f0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8a00: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8a10: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
8a20: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
8a30: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
8a40: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
8a50: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
8a60: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
8a70: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
8a80: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
8a90: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8aa0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8ab0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8ac0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8ad0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8ae0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8af0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
8b00: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8b10: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
8b20: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
8b30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8b40: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8b50: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8b60: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8b70: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8b80: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8b90: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8ba0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8bb0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8bc0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8bd0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8be0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8bf0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8c00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8c10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8c20: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8c30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8c40: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8c50: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8c60: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8c70: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8c80: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8c90: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8ca0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8cb0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8cc0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8cd0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8ce0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8cf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8d00: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8d10: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8d20: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8d30: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8d40: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8d50: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8d60: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8d70: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8d80: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8d90: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8da0: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8db0: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8dc0: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8dd0: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8de0: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8df0: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8e00: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8e10: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8e20: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8e30: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8e40: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8e50: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8e60: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8e70: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8e80: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8e90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8ea0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8eb0: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8ec0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8ed0: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8ee0: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8ef0: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8f00: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8f10: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8f20: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8f30: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8f40: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8f50: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8f60: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8f70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8f80: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8f90: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8fa0: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8fb0: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8fc0: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8fd0: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8fe0: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
8ff0: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
9000: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
9010: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
9020: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
9030: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
9040: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
9050: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
9060: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
9070: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
9080: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9090: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
90a0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
90b0: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
90c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
90d0: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
90e0: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
90f0: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9100: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9110: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9120: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
9130: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9140: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9150: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
9160: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9170: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
9180: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
9190: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
91a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
91b0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
91c0: 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65  ITTED]].** ^(The
91d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
91e0: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
91f0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9200: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
9210: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
9220: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
9230: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
9240: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
9250: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
9260: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
9270: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
9280: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
9290: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
92a0: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
92b0: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
92c0: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
92d0: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
92e0: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
92f0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9300: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9310: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
9320: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
9330: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
9340: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
9350: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
9360: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9370: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
9380: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9390: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
93a0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
93b0: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
93c0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
93d0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
93e0: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
93f0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9400: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
9410: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9420: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9430: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9440: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9450: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9460: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9470: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9480: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9490: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
94a0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
94b0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
94c0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
94d0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
94e0: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
94f0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9500: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9510: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9520: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9530: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9540: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9550: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9560: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9570: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9580: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9590: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
95a0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
95b0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
95c0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
95d0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
95e0: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
95f0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9600: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9610: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9620: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9630: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9640: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9650: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9660: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9670: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9680: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9690: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
96a0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
96b0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
96c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
96d0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
96e0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
96f0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9700: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9710: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9720: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9730: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9740: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9750: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9760: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9770: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9780: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9790: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
97a0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
97b0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
97c0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
97d0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
97e0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
97f0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9800: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9810: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9820: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9830: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9840: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9850: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9860: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9870: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9880: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9890: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
98a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
98b0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
98c0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
98d0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
98e0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
98f0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9900: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9910: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9920: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9930: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9940: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9950: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9960: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9970: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9980: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9990: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
99a0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
99b0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
99c0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
99d0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
99e0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
99f0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9a00: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9a10: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9a20: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9a30: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9a40: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9a50: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9a60: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9a70: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9a80: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9a90: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9aa0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9ab0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9ac0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9ad0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9ae0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9af0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9b00: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9b10: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9b20: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9b30: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9b40: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9b50: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9b60: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9b70: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9b80: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9b90: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9ba0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9bb0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9bc0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9bd0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9be0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9bf0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9c00: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9c10: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9c20: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9c30: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9c40: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9c50: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9c60: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9c70: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9c80: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9c90: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9ca0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9cb0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9cc0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9cd0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9ce0: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9cf0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9d00: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9d10: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9d20: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9d30: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9d40: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9d50: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9d60: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9d70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9d80: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9d90: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9da0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9db0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9dc0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9dd0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9de0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9df0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9e00: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
9e10: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e20: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e30: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e40: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9e50: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
9e60: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
9e70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9e80: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9e90: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9ea0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9eb0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9ec0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
9ed0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
9ee0: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
9ef0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
9f00: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
9f10: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
9f20: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
9f30: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
9f40: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9f50: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
9f60: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
9f70: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
9f80: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
9f90: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
9fa0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
9fb0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9fc0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
9fd0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9fe0: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
9ff0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a000: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a010: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a020: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a030: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a040: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a050: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a060: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a070: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a080: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a090: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a0a0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a0b0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a0c0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a0d0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a0e0: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a0f0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a100: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a110: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a120: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a130: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a140: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a150: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a160: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a170: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a180: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a190: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a1a0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a1b0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a1c0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a1d0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a1e0: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a1f0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a200: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a210: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a220: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a230: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a240: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a250: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a260: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a270: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a280: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a290: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a2a0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a2b0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a2c0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a2d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a2e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a2f0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a300: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a310: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a320: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a330: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a340: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a350: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a360: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a370: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a380: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a390: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a3a0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a3b0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a3c0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a3d0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a3e0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a3f0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a400: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a410: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a420: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a430: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a440: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a450: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a460: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a470: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a480: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a490: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a4a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a4b0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a4c0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a4d0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a4e0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a4f0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a500: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a510: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a520: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a530: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a540: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a550: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a560: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a570: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a580: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a590: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a5a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a5b0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a5c0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a5d0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a5e0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a5f0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a600: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a610: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a620: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a630: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a640: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a650: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a660: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a670: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a680: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a690: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a6a0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a6b0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a6c0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a6d0: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a6e0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a6f0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a700: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a710: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a720: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a730: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a740: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a750: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a760: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
a770: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
a780: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
a790: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
a7a0: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
a7b0: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
a7c0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
a7d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a7e0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a7f0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
a800: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
a810: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
a820: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
a830: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
a840: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
a850: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
a860: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
a870: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a880: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a890: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a8a0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
a8b0: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
a8c0: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
a8d0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
a8e0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
a8f0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
a900: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
a910: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
a920: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
a930: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
a940: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
a950: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
a960: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
a970: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
a980: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
a990: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
a9a0: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
a9b0: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
a9c0: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
a9d0: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
a9e0: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
a9f0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
aa00: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aa10: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
aa20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
aa30: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
aa40: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
aa50: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
aa60: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
aa70: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
aa80: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
aa90: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
aaa0: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
aab0: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
aac0: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
aad0: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
aae0: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
aaf0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ab00: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ab10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
ab20: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
ab30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ab40: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ab50: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
ab60: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ab70: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ab80: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ab90: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
aba0: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
abb0: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
abc0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
abd0: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
abe0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
abf0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ac00: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
ac10: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
ac20: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
ac30: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
ac40: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
ac50: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
ac60: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
ac70: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
ac80: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
ac90: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
aca0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
acb0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
acc0: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
acd0: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
ace0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
acf0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
ad00: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
ad10: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
ad20: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ad30: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
ad40: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
ad50: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
ad60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
ad70: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
ad80: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
ad90: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
ada0: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
adb0: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
adc0: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
add0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
ade0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
adf0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
ae00: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
ae10: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
ae20: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
ae30: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
ae40: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
ae50: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
ae60: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
ae70: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
ae80: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
ae90: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
aea0: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
aeb0: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
aec0: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
aed0: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
aee0: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
aef0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
af00: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
af10: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
af20: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
af30: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
af40: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
af50: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
af60: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
af70: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
af80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
af90: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
afa0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
afb0: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
afc0: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
afd0: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
afe0: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
aff0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b000: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b010: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b020: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b030: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b040: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b050: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b060: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b070: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b080: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b090: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b0a0: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b0b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b0c0: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b0d0: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b0e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b0f0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b100: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b110: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b120: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b130: 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  **.** </ul>.*/.#
b140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b150: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
b160: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
b170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
b180: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
b190: 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
b1a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
b1b0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
b1c0: 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
b1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
b1e0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
b1f0: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
b200: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b210: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
b220: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
b230: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
b240: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
b250: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
b260: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
b270: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
b280: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
b290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b2a0: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
b2b0: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
b2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
b2d0: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
b2e0: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
b2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
b300: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
b310: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
b320: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
b330: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
b340: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
b350: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
b360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b370: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
b380: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
b390: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
b3a0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
b3b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
b3d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b3e0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b3f0: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
b400: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b410: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
b420: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
b430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b440: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
b450: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
b460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b470: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
b480: 20 20 20 20 20 20 20 20 20 20 31 39 0a 0a 2f 2a            19../*
b490: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
b4a0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
b4b0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
b4c0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
b4d0: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
b4e0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
b4f0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
b500: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
b510: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
b520: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
b530: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
b540: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
b550: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
b560: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
b570: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
b580: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
b590: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
b5a0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
b5b0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
b5c0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
b5d0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
b5e0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
b5f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
b600: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
b610: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
b620: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
b630: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
b640: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
b650: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
b660: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
b670: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
b680: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
b690: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
b6a0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
b6b0: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
b6c0: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
b6d0: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
b6e0: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
b6f0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
b700: 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20  m".  See.** the 
b710: 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d  [VFS | VFS docum
b720: 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75  entation] for fu
b730: 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f  rther informatio
b740: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  n..**.** The val
b750: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
b760: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
b770: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
b780: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
b790: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
b7a0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
b7b0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
b7c0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
b7d0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
b7e0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
b7f0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
b800: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
b810: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
b820: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
b830: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
b840: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
b850: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
b860: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
b870: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
b880: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
b890: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
b8a0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
b8b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
b8c0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
b8d0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
b8e0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
b8f0: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
b900: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
b910: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
b920: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
b930: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
b940: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
b950: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
b960: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
b970: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
b980: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
b990: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
b9a0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
b9b0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
b9c0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
b9d0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
b9e0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
b9f0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
ba00: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
ba10: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
ba20: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
ba30: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
ba40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
ba50: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
ba60: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
ba70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
ba80: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
ba90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
baa0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
bab0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
bac0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
bad0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
bae0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
baf0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
bb00: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
bb10: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
bb20: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
bb30: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
bb40: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
bb50: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
bb60: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
bb70: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
bb80: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
bb90: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
bba0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
bbb0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
bbc0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
bbd0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
bbe0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
bbf0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
bc00: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
bc10: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
bc20: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
bc30: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
bc40: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
bc50: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
bc60: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
bc70: 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e  vfs.xOpen]].** ^
bc80: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
bc90: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
bca0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
bcb0: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
bcc0: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
bcd0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
bce0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
bcf0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
bd00: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
bd10: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
bd20: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
bd30: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
bd40: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
bd50: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
bd60: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
bd70: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
bd80: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
bd90: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61  ore than.** 11 a
bda0: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
bdb0: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
bdc0: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
bdd0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
bde0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
bdf0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
be00: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
be10: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
be20: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
be30: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
be40: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
be50: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
be60: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
be70: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
be80: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
be90: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
bea0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
beb0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
bec0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
bed0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
bee0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
bef0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
bf00: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
bf10: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
bf20: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
bf30: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
bf40: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
bf50: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
bf60: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
bf70: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
bf80: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
bf90: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
bfa0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
bfb0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
bfc0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
bfd0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
bfe0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
bff0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
c000: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
c010: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c020: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
c030: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
c040: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c050: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
c060: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
c070: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
c080: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
c090: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
c0a0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
c0b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
c0c0: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
c0d0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
c0e0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
c0f0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
c100: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
c110: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
c120: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
c130: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
c140: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
c150: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
c160: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
c170: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
c180: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
c190: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
c1a0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
c1b0: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
c1c0: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
c1d0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c1e0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
c1f0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c200: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
c210: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c220: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
c230: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c240: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
c250: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c260: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
c270: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
c280: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
c290: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
c2a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c2b0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
c2c0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c2d0: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
c2e0: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
c2f0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
c300: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
c310: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
c320: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
c330: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
c340: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
c350: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
c360: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
c370: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
c380: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
c390: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
c3a0: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
c3b0: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
c3c0: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
c3d0: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
c3e0: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
c3f0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
c400: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
c410: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
c420: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
c430: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
c440: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
c450: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
c460: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
c470: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
c480: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
c490: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
c4a0: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
c4b0: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
c4c0: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
c4d0: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
c4e0: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
c4f0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
c500: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
c510: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
c520: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
c530: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
c540: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
c550: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
c560: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c570: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
c580: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
c590: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
c5a0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
c5b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
c5c0: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
c5d0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
c5e0: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
c5f0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
c600: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
c610: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c620: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
c630: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
c640: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
c650: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
c660: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
c670: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
c680: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
c690: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
c6a0: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
c6b0: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
c6c0: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
c6d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
c6e0: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
c6f0: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
c700: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
c710: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
c720: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
c730: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
c740: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
c750: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
c760: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
c770: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
c780: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
c790: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
c7a0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
c7b0: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
c7c0: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
c7d0: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
c7e0: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
c7f0: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
c800: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
c810: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
c820: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
c830: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
c840: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
c850: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
c860: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
c870: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
c880: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
c890: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
c8a0: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
c8b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c8c0: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
c8d0: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
c8e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
c8f0: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
c900: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
c910: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
c920: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
c930: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
c940: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
c950: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
c960: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
c970: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
c980: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
c990: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
c9a0: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
c9b0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
c9c0: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
c9d0: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
c9e0: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
c9f0: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
ca00: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
ca10: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
ca20: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
ca30: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
ca40: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
ca50: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
ca60: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
ca70: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
ca80: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
ca90: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
caa0: 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a  3_vfs.xAccess]].
cab0: 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72  ** ^The flags ar
cac0: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
cad0: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
cae0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
caf0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
cb00: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
cb10: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
cb20: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
cb30: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
cb40: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
cb50: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
cb60: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
cb70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
cb80: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
cb90: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
cba0: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
cbb0: 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
cbc0: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
cbd0: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ory..**.** ^SQLi
cbe0: 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61  te will always a
cbf0: 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74  llocate at least
cc00: 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79   mxPathname+1 by
cc10: 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f  tes for the.** o
cc20: 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75  utput buffer xFu
cc30: 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65  llPathname.  The
cc40: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
cc50: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
cc60: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
cc70: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
cc80: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
cc90: 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75  ds. If the outpu
cca0: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e  t buffer.** is n
ccb0: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
ccc0: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
ccd0: 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  N] should be ret
cce0: 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69  urned. Since thi
ccf0: 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20  s is.** handled 
cd00: 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  as a fatal error
cd10: 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20   by SQLite, vfs 
cd20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
cd30: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a  should endeavor.
cd40: 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ** to prevent th
cd50: 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78  is by setting mx
cd60: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75  Pathname to a su
cd70: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65  fficiently large
cd80: 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
cd90: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
cda0: 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72   xSleep(), xCurr
cdb0: 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78  entTime(), and x
cdc0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
cdd0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
cde0: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
cdf0: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
ce00: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
ce10: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
ce20: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
ce30: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
ce40: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
ce50: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
ce60: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
ce70: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
ce80: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
ce90: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
cea0: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
ceb0: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
cec0: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
ced0: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
cee0: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
cef0: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
cf00: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
cf10: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
cf20: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
cf30: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
cf40: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
cf50: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
cf60: 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20  ds given.  ^The 
cf70: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
cf80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
cf90: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
cfa0: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
cfb0: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
cfc0: 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74  me as.** a float
cfd0: 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e  ing point value.
cfe0: 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e  .** ^The xCurren
cff0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d000: 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20  hod returns, as 
d010: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20  an integer, the 
d020: 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75  Julian.** Day Nu
d030: 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20  mber multiplied 
d040: 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65  by 86400000 (the
d050: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
d060: 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61  seconds in .** a
d070: 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20   24-hour day).  
d080: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d090: 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e   use the xCurren
d0a0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d0b0: 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63  hod to get the c
d0c0: 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61  urrent.** date a
d0d0: 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20  nd time if that 
d0e0: 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61  method is availa
d0f0: 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e  ble (if iVersion
d100: 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65   is 2 or .** gre
d110: 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e  ater and the fun
d120: 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
d130: 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77   not NULL) and w
d140: 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a  ill fall back.**
d150: 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65   to xCurrentTime
d160: 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69  () if xCurrentTi
d170: 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61  meInt64() is una
d180: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  vailable..**.** 
d190: 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43  ^The xSetSystemC
d1a0: 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65  all(), xGetSyste
d1b0: 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65  mCall(), and xNe
d1c0: 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69  stSystemCall() i
d1d0: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
d1e0: 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65   not used by the
d1f0: 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54   SQLite core.  T
d200: 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e  hese optional in
d210: 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
d220: 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65  vided.** by some
d230: 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69   VFSes to facili
d240: 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20  tate testing of 
d250: 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79  the VFS code. By
d260: 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20   overriding .** 
d270: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74  system calls wit
d280: 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65  h functions unde
d290: 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61  r its control, a
d2a0: 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61   test program ca
d2b0: 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61  n.** simulate fa
d2c0: 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63  ults and error c
d2d0: 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77  onditions that w
d2e0: 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62  ould otherwise b
d2f0: 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f  e difficult.** o
d300: 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20  r impossible to 
d310: 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74  induce.  The set
d320: 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73   of system calls
d330: 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
d340: 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65  rridden.** varie
d350: 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74  s from one VFS t
d360: 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66  o another, and f
d370: 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20  rom one version 
d380: 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  of the same VFS 
d390: 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20  to the.** next. 
d3a0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
d3b0: 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74  at use these int
d3c0: 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20  erfaces must be 
d3d0: 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79  prepared for any
d3e0: 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68  .** or all of th
d3f0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74  ese interfaces t
d400: 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72  o be NULL or for
d410: 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20   their behavior 
d420: 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f  to change.** fro
d430: 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f  m one release to
d440: 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c   the next.  Appl
d450: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f  ications must no
d460: 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63  t attempt to acc
d470: 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68  ess.** any of th
d480: 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74  ese methods if t
d490: 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74  he iVersion of t
d4a0: 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74  he VFS is less t
d4b0: 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65  han 3..*/.typede
d4c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
d4d0: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
d4e0: 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  ;.typedef void (
d4f0: 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c  *sqlite3_syscall
d500: 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72  _ptr)(void);.str
d510: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
d520: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
d530: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
d540: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
d550: 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
d560: 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 3) */.  int 
d570: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
d580: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
d590: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
d5a0: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
d5b0: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
d5c0: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
d5d0: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
d5e0: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
d5f0: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
d600: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
d610: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
d620: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d630: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
d640: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
d650: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
d660: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
d670: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
d680: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
d690: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
d6a0: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
d6b0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
d6c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d6d0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
d6e0: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
d6f0: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
d700: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
d710: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
d720: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d730: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d740: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
d750: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
d760: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d770: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d780: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
d790: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
d7a0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
d7b0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
d7c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d7d0: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
d7e0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
d7f0: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
d800: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
d810: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
d820: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
d830: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
d840: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
d850: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
d860: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
d870: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
d880: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
d890: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
d8a0: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
d8b0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
d8c0: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
d8d0: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
d8e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d8f0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
d900: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
d910: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
d920: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
d930: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
d940: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
d950: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
d960: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
d970: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
d980: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
d990: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
d9a0: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
d9b0: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
d9c0: 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
d9d0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
d9e0: 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
d9f0: 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
da00: 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
da10: 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
da20: 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
da30: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74  *xCurrentTimeInt
da40: 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  64)(sqlite3_vfs*
da50: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a  , sqlite3_int64*
da60: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
da70: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
da80: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
da90: 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71   and 2 of the sq
daa0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
dab0: 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f  .  ** Those belo
dac0: 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f  w are for versio
dad0: 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e  n 3 and greater.
dae0: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  .  */.  int (*xS
daf0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
db00: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
db10: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
db20: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
db30: 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73  tr);.  sqlite3_s
db40: 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65  yscall_ptr (*xGe
db50: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
db60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
db70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
db80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78   const char *(*x
db90: 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  NextSystemCall)(
dba0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
dbb0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
dbc0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
dbd0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
dbe0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
dbf0: 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65  through 3 of the
dc00: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
dc10: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
dc20: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
dc30: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
dc40: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
dc50: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
dc60: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
dc70: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
dc80: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
dc90: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
dca0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
dcb0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
dcc0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
dcd0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
dce0: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
dcf0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
dd00: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
dd10: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
dd20: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
dd30: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
dd40: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
dd50: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
dd60: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
dd70: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
dd80: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
dd90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
dda0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
ddb0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
ddc0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
ddd0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
dde0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ddf0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
de00: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
de10: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
de20: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
de30: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
de40: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
de50: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
de60: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
de70: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
de80: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
de90: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
dea0: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
deb0: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
dec0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ded0: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
dee0: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
def0: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
df00: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
df10: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
df20: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
df30: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
df40: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
df50: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
df60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
df70: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
df80: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
df90: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
dfa0: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
dfb0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
dfc0: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
dfd0: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
dfe0: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
dff0: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
e000: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
e010: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
e020: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
e030: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
e040: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
e050: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e060: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
e070: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
e080: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
e090: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e0a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
e0b0: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
e0c0: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
e0d0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e0e0: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
e0f0: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
e100: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
e110: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
e120: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
e130: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
e140: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
e150: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
e160: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
e170: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
e180: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
e190: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
e1a0: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
e1b0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
e1c0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
e1d0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
e1e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e1f0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e200: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e210: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
e220: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e230: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
e240: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e250: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
e260: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
e270: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
e280: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e290: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
e2a0: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
e2b0: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
e2c0: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
e2d0: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
e2e0: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
e2f0: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
e300: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
e310: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
e320: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
e330: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
e340: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
e350: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
e360: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
e370: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
e380: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
e390: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
e3a0: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
e3b0: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
e3c0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
e3d0: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
e3e0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
e3f0: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
e400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
e410: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
e420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e430: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
e440: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
e450: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
e460: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
e470: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
e480: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
e490: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
e4a0: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
e4b0: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
e4c0: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
e4d0: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
e4e0: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
e4f0: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
e500: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
e510: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
e520: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
e530: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
e540: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
e550: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
e560: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
e570: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
e580: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
e590: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
e5a0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
e5b0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
e5c0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
e5d0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
e5e0: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
e5f0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
e600: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
e610: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
e620: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
e630: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
e640: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
e650: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
e660: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
e670: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
e680: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
e690: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
e6a0: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
e6b0: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
e6c0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
e6d0: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
e6e0: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
e6f0: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
e700: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
e710: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
e720: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
e730: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
e740: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
e750: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
e760: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
e770: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e780: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
e790: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
e7a0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
e7b0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
e7c0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
e7d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e7e0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
e7f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
e800: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e810: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
e820: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
e830: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
e840: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
e850: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
e860: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
e870: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
e880: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
e890: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
e8a0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e8b0: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
e8c0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
e8d0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
e8e0: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
e8f0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
e900: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
e910: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e920: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
e930: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
e940: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e950: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
e960: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
e970: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
e980: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
e990: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e9a0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
e9b0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
e9c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e9d0: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
e9e0: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
e9f0: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
ea00: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
ea10: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
ea20: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
ea30: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
ea40: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
ea50: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
ea60: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
ea70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
ea80: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
ea90: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
eaa0: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
eab0: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
eac0: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
ead0: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
eae0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
eaf0: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
eb00: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
eb10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
eb20: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
eb30: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
eb40: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
eb50: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eb60: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
eb70: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
eb80: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
eb90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eba0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
ebb0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
ebc0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
ebd0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
ebe0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
ebf0: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
ec00: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
ec10: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
ec20: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
ec30: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
ec40: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
ec50: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
ec60: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
ec70: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
ec80: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
ec90: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
eca0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ecb0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
ecc0: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
ecd0: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
ece0: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
ecf0: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
ed00: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
ed10: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
ed20: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
ed30: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
ed40: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
ed50: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
ed60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ed70: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
ed80: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
ed90: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
eda0: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
edb0: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
edc0: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
edd0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
ede0: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
edf0: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
ee00: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
ee10: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
ee20: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
ee30: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
ee40: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
ee50: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
ee60: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
ee70: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
ee80: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
ee90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
eea0: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
eeb0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
eec0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
eed0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
eee0: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
eef0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ef00: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ef10: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
ef20: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
ef30: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
ef40: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
ef50: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
ef60: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
ef70: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
ef80: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
ef90: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
efa0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
efb0: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
efc0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
efd0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
efe0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
eff0: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
f000: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
f010: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f020: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
f030: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
f040: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
f050: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
f060: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
f070: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
f080: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
f090: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f0a0: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
f0b0: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
f0c0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
f0d0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
f0e0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f0f0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
f100: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
f110: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
f120: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
f130: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
f140: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
f150: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
f160: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
f170: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
f180: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
f190: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
f1a0: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
f1b0: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
f1c0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
f1d0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
f1e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
f1f0: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
f200: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
f210: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
f220: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
f230: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
f240: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f250: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
f260: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
f270: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
f280: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
f290: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
f2a0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
f2b0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
f2c0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
f2d0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
f2e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f2f0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
f300: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
f310: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
f320: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
f330: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f340: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
f350: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
f360: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
f370: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f380: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
f390: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
f3a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
f3b0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
f3c0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
f3d0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
f3e0: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
f3f0: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
f400: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
f410: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
f420: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
f430: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
f440: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
f450: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
f460: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
f470: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
f480: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f490: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
f4a0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
f4b0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
f4c0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f4d0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
f4e0: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
f4f0: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
f500: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f510: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
f520: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
f530: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
f540: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
f550: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
f560: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
f570: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
f580: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
f590: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
f5a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f5b0: 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  e(void);.SQLITE_
f5c0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
f5d0: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
f5e0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
f5f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
f600: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
f610: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
f620: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
f630: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
f640: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
f650: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
f660: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
f670: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
f680: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
f690: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
f6a0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
f6b0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
f6c0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
f6d0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
f6e0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
f6f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
f700: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
f710: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
f720: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
f730: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
f740: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
f750: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
f760: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
f770: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
f780: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
f790: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
f7a0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
f7b0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
f7c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f7d0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
f7e0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
f7f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
f800: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
f810: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
f820: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
f830: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
f840: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
f850: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
f860: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
f870: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
f880: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
f890: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
f8a0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
f8b0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
f8c0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
f8d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f8e0: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
f8f0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
f900: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
f910: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
f920: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
f930: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
f940: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
f950: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
f960: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f970: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
f980: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
f990: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
f9a0: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
f9b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
f9c0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
f9d0: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
f9e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
f9f0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
fa00: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
fa10: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
fa20: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
fa30: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
fa40: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
fa50: 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
fa60: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
fa70: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
fa80: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
fa90: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
faa0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
fab0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
fac0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
fad0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
fae0: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
faf0: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
fb00: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
fb10: 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
fb20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
fb30: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
fb40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
fb50: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
fb60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
fb70: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
fb80: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
fb90: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
fba0: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
fbb0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
fbc0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
fbd0: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51  ror code]..*/.SQ
fbe0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
fbf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
fc00: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
fc10: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
fc20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
fc30: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
fc40: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
fc50: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
fc60: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
fc70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
fc80: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
fc90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fca0: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
fcb0: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
fcc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
fcd0: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
fce0: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
fcf0: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
fd00: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
fd10: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
fd20: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
fd30: 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
fd40: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
fd50: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
fd60: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
fd70: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
fd80: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
fd90: 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
fda0: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
fdb0: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
fdc0: 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
fdd0: 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
fde0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
fdf0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
fe00: 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
fe10: 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
fe20: 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
fe30: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
fe40: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
fe50: 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
fe60: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
fe70: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
fe80: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
fe90: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
fea0: 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
feb0: 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
fec0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
fed0: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
fee0: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
fef0: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
ff00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
ff10: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
ff20: 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
ff30: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
ff40: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
ff50: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
ff60: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
ff70: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
ff80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ff90: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
ffa0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
ffb0: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
ffc0: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
ffd0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
ffe0: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
fff0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
10000 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
10010 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
10020 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10030 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
10040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10050 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
10060 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
10070 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
10080 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
10090 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
100a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
100b0 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
100c0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
100d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
100e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
100f0 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
10100 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
10110 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
10120 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
10130 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
10140 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
10150 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
10160 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
10170 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
10180 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
10190 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
101a0 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
101b0 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
101c0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
101d0 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
101e0 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
101f0 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
10200 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
10210 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
10220 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
10230 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
10240 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
10250 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
10260 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
10270 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
10280 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
10290 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
102a0 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
102b0 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
102c0 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
102d0 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
102e0 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
102f0 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
10300 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10310 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
10320 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
10330 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
10340 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
10350 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
10360 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
10370 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
10380 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
10390 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
103a0 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
103b0 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
103c0 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
103d0 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
103e0 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
103f0 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
10400 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
10410 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
10420 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
10430 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
10440 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10450 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
10460 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
10470 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
10480 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
10490 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
104a0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
104b0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
104c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
104d0 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
104e0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
104f0 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
10500 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
10510 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
10520 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
10530 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
10540 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
10550 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
10560 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
10570 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
10580 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
10590 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
105a0 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
105b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
105c0 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
105d0 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
105e0 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
105f0 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
10600 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
10610 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
10620 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
10630 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
10640 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
10650 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
10660 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
10670 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
10680 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
10690 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
106a0 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
106b0 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
106c0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
106d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
106e0 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
106f0 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
10700 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
10710 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
10720 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
10730 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
10740 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
10750 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
10760 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
10770 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
10780 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
10790 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
107a0 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
107b0 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
107c0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
107d0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
107e0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
107f0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10800 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
10810 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
10820 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10830 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
10840 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
10850 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
10860 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
10870 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
10880 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
10890 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
108a0 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
108b0 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
108c0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
108d0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
108e0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
108f0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
10900 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
10910 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
10920 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
10930 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
10940 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
10950 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10960 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
10970 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
10980 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
10990 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
109a0 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
109b0 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
109c0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
109d0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
109e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
109f0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
10a00 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
10a10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
10a20 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10a40 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
10a50 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
10a60 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
10a70 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
10a80 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
10a90 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
10aa0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
10ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10ac0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
10ad0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
10ae0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
10af0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
10b00 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
10b10 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
10b20 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
10b30 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
10b40 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
10b50 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
10b60 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
10b70 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
10b80 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
10b90 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
10ba0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
10bb0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
10bc0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
10bd0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
10be0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
10bf0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
10c00 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
10c10 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
10c20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10c30 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
10c40 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
10c50 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
10c60 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
10c70 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
10c80 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
10c90 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
10ca0 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
10cb0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
10cc0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
10cd0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
10ce0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
10cf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
10d00 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
10d10 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
10d20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
10d30 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
10d40 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
10d50 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
10d60 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
10d70 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
10d80 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10d90 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
10da0 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
10db0 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
10dc0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
10dd0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
10de0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
10df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
10e00 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
10e10 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
10e20 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
10e30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10e40 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
10e50 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
10e60 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
10e70 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
10e80 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
10e90 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
10ea0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
10eb0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
10ec0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
10ed0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
10ee0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
10ef0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10f00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
10f10 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
10f20 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10f30 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
10f40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
10f50 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
10f60 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
10f70 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
10f80 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
10f90 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
10fa0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
10fb0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
10fc0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
10fd0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
10fe0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
10ff0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11000 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11010 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11020 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11030 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11040 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11050 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11060 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
11070 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
11080 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
11090 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
110a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
110b0 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
110c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
110d0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
110e0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
110f0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11100 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11110 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11120 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11130 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
11140 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11150 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11160 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
11170 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
11180 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
11190 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
111a0 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
111b0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
111c0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
111d0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
111e0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
111f0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11200 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11210 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11220 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11230 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11240 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
11250 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11260 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
11270 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
11280 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
11290 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
112a0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
112b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
112c0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
112d0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
112e0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
112f0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11300 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11310 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11320 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11330 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11340 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11350 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11360 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11370 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11380 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11390 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
113a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
113b0 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
113c0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
113d0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
113e0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
113f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11400 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11410 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11420 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
11430 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
11440 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
11450 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
11460 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11470 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
11480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11490 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
114a0 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
114b0 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
114c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
114d0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
114e0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
114f0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
11500 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
11510 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
11520 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
11530 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11540 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
11550 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
11560 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11570 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11580 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11590 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
115a0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
115b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
115c0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
115d0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
115e0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
115f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11600 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11610 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11620 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11630 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11640 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11650 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11660 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
11670 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11680 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11690 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
116a0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
116b0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
116c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
116d0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
116e0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
116f0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11700 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11710 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11720 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
11730 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11740 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
11750 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
11760 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
11770 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
11780 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
11790 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
117a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
117b0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
117c0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
117d0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
117e0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
117f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11800 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
11810 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
11820 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11830 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
11840 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
11850 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
11860 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11870 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11880 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
11890 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
118a0 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
118b0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
118c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
118d0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
118e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
118f0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
11900 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
11910 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
11920 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11930 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11940 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11950 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11960 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11970 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11980 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11990 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
119a0 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
119b0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
119c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
119d0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
119e0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
119f0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11a00 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
11a10 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11a30 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11a40 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11a50 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
11a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11a70 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
11a80 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11a90 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11aa0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11ab0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11ac0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
11ad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
11ae0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11af0 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
11b00 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
11b10 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
11b20 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
11b30 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
11b40 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
11b50 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
11b60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11b70 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
11b80 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
11b90 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
11ba0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
11bb0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
11bc0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
11bd0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
11be0 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
11bf0 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
11c00 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
11c10 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
11c20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11c30 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
11c40 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11c50 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
11c60 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
11c70 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
11c80 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
11c90 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
11ca0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
11cb0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
11cc0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11cd0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
11ce0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
11cf0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
11d00 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
11d10 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
11d20 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
11d30 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
11d40 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
11d50 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
11d60 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
11d70 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
11d80 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
11d90 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
11da0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
11db0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
11dc0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
11dd0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
11de0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
11df0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
11e00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11e10 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
11e20 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11e30 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
11e40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11e50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
11e60 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
11e70 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
11e80 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
11e90 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
11ea0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
11eb0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
11ec0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
11ed0 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
11ee0 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
11ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11f00 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
11f10 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
11f20 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
11f30 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
11f40 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
11f50 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
11f60 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
11f70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
11f80 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11f90 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
11fa0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
11fb0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
11fc0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
11fd0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11fe0 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
11ff0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12000 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12010 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12020 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12030 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12040 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12050 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12060 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
12070 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
12080 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
12090 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
120a0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
120b0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
120c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
120d0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
120e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
120f0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
12100 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12110 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
12120 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12130 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12140 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
12150 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
12160 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
12170 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
12180 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
12190 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
121a0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
121b0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
121c0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
121d0 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
121e0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
121f0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12200 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
12210 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
12220 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
12230 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
12240 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
12250 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
12260 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
12270 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
12280 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
12290 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
122a0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
122b0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
122c0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
122d0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
122e0 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
122f0 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
12300 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
12310 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
12320 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
12330 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
12340 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
12350 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
12360 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12370 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
12380 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
12390 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
123a0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
123b0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
123c0 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
123d0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
123e0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
123f0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
12400 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
12410 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
12420 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
12430 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
12440 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
12450 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
12460 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
12470 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
12480 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
12490 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
124a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
124b0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
124c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
124d0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
124e0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
124f0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
12500 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
12510 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
12520 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
12530 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
12540 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
12550 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
12560 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
12570 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
12580 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
12590 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
125a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
125b0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
125c0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
125d0 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
125e0 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
125f0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
12600 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
12610 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
12620 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
12630 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
12640 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
12650 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
12660 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
12670 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
12680 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
12690 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
126a0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
126b0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
126c0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
126d0 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
126e0 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
126f0 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
12700 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
12710 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
12720 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
12730 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
12740 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
12750 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
12760 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
12770 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
12780 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
12790 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
127a0 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
127b0 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
127c0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
127d0 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
127e0 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
127f0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
12800 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
12810 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
12820 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
12830 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
12840 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
12850 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
12860 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
12870 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
12880 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
12890 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
128a0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
128b0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
128c0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
128d0 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
128e0 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
128f0 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
12900 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
12910 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
12920 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
12930 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
12940 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
12950 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
12960 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
12970 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
12980 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
12990 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
129a0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
129b0 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
129c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
129d0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
129e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
129f0 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
12a00 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12a10 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12a20 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12a30 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
12a40 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
12a50 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
12a60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12a70 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
12a80 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
12a90 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
12aa0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
12ab0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
12ac0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
12ad0 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
12ae0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
12af0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
12b00 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
12b10 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
12b20 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
12b30 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
12b40 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
12b50 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
12b60 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
12b70 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
12b80 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
12b90 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
12ba0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
12bb0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
12bc0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
12bd0 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
12be0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
12bf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
12c00 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
12c10 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
12c20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12c30 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
12c40 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
12c50 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
12c60 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
12c70 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
12c80 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
12c90 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
12ca0 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
12cb0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
12cc0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
12cd0 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
12ce0 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
12cf0 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
12d00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
12d10 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
12d20 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
12d30 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
12d40 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
12d50 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
12d60 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
12d70 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
12d80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
12d90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
12da0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
12db0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
12dc0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
12dd0 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
12de0 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
12df0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
12e00 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
12e10 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
12e20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12e30 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
12e40 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
12e50 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
12e60 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12e70 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12e80 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12e90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12ea0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
12eb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
12ec0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
12ed0 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
12ee0 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
12ef0 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
12f00 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
12f10 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
12f20 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
12f30 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
12f40 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
12f50 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
12f60 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
12f70 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
12f80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
12f90 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
12fa0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
12fb0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
12fc0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12fd0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
12fe0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12ff0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13000 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13010 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13020 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13030 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13040 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13050 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13060 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
13070 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
13080 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
13090 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
130a0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
130b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
130c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
130d0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
130e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
130f0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13100 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13110 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
13120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13130 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13140 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13150 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13160 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13170 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13180 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
13190 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
131a0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
131b0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
131c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
131d0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
131e0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
131f0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13200 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
13210 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
13220 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
13230 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
13240 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
13250 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
13260 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
13270 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
13280 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
13290 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
132a0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
132b0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
132c0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
132d0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
132e0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
132f0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13300 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13310 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13320 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13330 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13340 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13350 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13360 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
13370 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
13380 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13390 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
133a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
133b0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
133c0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
133d0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
133e0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
133f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13400 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
13410 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13420 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
13430 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
13440 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13450 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
13460 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
13470 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
13480 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
13490 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
134a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
134b0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
134c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
134d0 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
134e0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
134f0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
13500 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
13510 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
13520 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13530 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
13540 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
13550 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13560 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
13570 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
13580 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
13590 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
135a0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
135b0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
135c0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
135d0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
135e0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
135f0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
13600 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
13610 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
13620 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
13630 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13650 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
13660 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13670 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13680 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13690 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
136a0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
136b0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
136c0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
136d0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
136e0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
136f0 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
13700 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
13710 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
13720 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13730 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13740 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
13750 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
13760 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
13770 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
13780 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
13790 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
137a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
137b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
137c0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
137d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
137e0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
137f0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13800 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13810 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
13820 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13830 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
13840 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
13850 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
13860 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
13870 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
13880 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
13890 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
138a0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
138b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
138c0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
138d0 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
138e0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
138f0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
13900 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
13910 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
13920 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
13930 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13940 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
13950 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
13960 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
13970 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
13980 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
13990 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
139a0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
139b0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
139c0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
139d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
139e0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
139f0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
13a00 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
13a10 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
13a20 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
13a30 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13a40 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
13a50 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
13a60 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
13a70 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
13a80 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
13a90 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
13aa0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
13ab0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
13ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13ad0 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
13ae0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
13af0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
13b00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
13b10 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
13b20 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
13b30 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
13b40 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
13b50 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
13b60 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
13b70 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
13b80 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
13b90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
13ba0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
13bb0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
13bc0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
13bd0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
13be0 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
13bf0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
13c00 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
13c10 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
13c20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
13c30 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
13c40 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
13c50 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
13c60 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
13c70 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
13c80 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
13c90 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
13ca0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
13cb0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
13cc0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
13cd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13ce0 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
13cf0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
13d00 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
13d10 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
13d20 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
13d30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
13d40 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
13d50 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
13d60 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
13d70 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13d80 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
13d90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
13da0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20  I.** <dd>^(This 
13db0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13dc0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
13dd0 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e  f type int. If n
13de0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a  on-zero, then.**
13df0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
13e00 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
13e10 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
13e20 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  ter is zero, the
13e30 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a  n URI handling.*
13e40 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  * is globally di
13e50 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
13e60 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
13e70 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
13e80 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
13e90 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
13ea0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
13eb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
13ec0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
13ed0 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
13ee0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
13ef0 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
13f00 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
13f10 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
13f20 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
13f30 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
13f40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
13f50 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
13f60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
13f70 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
13f80 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
13f90 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
13fa0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
13fb0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
13fc0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
13fd0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
13fe0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
13ff0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
14000 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14010 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
14020 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
14030 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14040 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
14050 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
14060 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
14070 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
14080 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
14090 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
140a0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
140b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
140c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
140d0 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
140e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
140f0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
14100 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
14110 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14120 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
14130 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
14140 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
14150 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
14160 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
14170 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
14180 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
14190 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
141a0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
141b0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
141c0 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  r.  ^The default
141d0 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
141e0 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
141f0 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
14200 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14210 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
14220 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
14230 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
14240 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14250 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
14260 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
14270 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
14280 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14290 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
142a0 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
142b0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
142c0 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
142d0 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
142e0 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
142f0 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
14300 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
14310 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
14320 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
14330 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
14340 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14350 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
14360 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
14370 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
14380 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
14390 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
143a0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
143b0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
143c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
143d0 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
143e0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
143f0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14400 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
14410 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
14420 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
14430 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
14440 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
14450 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
14460 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
14470 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
14480 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
14490 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
144a0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
144b0 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
144c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
144d0 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
144e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
144f0 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
14500 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
14510 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
14520 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
14530 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
14540 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
14550 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
14560 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
14570 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
14580 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
14590 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
145a0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
145b0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
145c0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
145d0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
145e0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
145f0 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
14600 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
14610 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
14620 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
14630 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
14640 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
14650 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
14660 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
14670 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
14680 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
14690 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
146a0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
146b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
146c0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
146d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
146e0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
146f0 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
14700 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
14710 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
14720 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
14730 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
14740 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
14750 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
14760 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
14770 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
14780 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
14790 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
147a0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
147b0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
147c0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
147d0 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
147e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
147f0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
14800 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
14810 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
14820 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
14830 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
14840 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
14850 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
14860 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
14870 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
14880 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
14890 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
148a0 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
148b0 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
148c0 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
148d0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
148e0 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
148f0 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
14900 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14910 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
14920 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14930 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
14940 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
14950 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
14960 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
14970 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
14980 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
14990 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
149a0 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
149b0 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
149c0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
149d0 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
149e0 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
149f0 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
14a00 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
14a10 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
14a20 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
14a30 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
14a40 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
14a50 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
14a60 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
14a70 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
14a80 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
14a90 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
14aa0 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
14ab0 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
14ac0 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
14ad0 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
14ae0 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63  e.** cannot be c
14af0 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69  hanged at run-ti
14b00 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65  me.  Nor may the
14b10 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
14b20 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78   mmap size.** ex
14b30 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65  ceed the compile
14b40 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
14b50 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
14b60 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
14b70 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
14b80 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14b90 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
14ba0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
14bb0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
14bc0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
14bd0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
14be0 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
14bf0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
14c00 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ult..** </dl>.*/
14c10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14c20 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
14c30 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
14c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14c50 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
14c60 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
14c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14c80 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
14c90 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
14ca0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14cb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
14cc0 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
14cd0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14ce0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
14cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14d00 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
14d10 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14d20 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14d40 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
14d50 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
14d60 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
14d70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d80 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
14d90 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
14da0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
14db0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14dc0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
14dd0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
14de0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
14df0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14e00 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14e10 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
14e20 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
14e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14e40 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
14e50 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
14e60 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
14e70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14e80 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
14e90 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
14ea0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
14eb0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
14ec0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
14ed0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
14ee0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
14ef0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
14f00 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14f10 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
14f20 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14f40 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
14f50 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
14f60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14f70 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
14f80 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
14f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14fa0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
14fb0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
14fc0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
14fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14fe0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
14ff0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
15000 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15010 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
15020 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
15030 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
15040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15050 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
15060 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
15070 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
15080 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15090 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
150a0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
150b0 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
150c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
150d0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
150e0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
150f0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15100 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15110 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
15120 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
15130 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
15140 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
15150 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
15160 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
15170 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
15180 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
15190 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
151a0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
151b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
151c0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
151d0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
151e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
151f0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
15200 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
15210 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
15220 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
15230 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
15240 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
15250 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
15260 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
15270 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15280 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
15290 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
152a0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
152b0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
152c0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
152d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
152e0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
152f0 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
15300 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
15310 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
15320 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
15330 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
15340 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
15350 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
15360 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
15370 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
15380 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
15390 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
153a0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
153b0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
153c0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
153d0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
153e0 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
153f0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
15400 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
15410 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
15420 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
15430 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
15440 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
15450 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15460 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
15470 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
15480 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15490 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
154a0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
154b0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
154c0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
154d0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
154e0 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
154f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15500 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
15510 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15520 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
15530 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
15540 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
15550 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
15560 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
15570 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
15580 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
15590 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
155a0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
155b0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
155c0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
155d0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
155e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
155f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15600 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
15610 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
15620 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
15630 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
15640 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
15650 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
15660 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
15670 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
15680 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
15690 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
156a0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
156b0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
156c0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
156d0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
156e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
156f0 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
15700 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
15710 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
15720 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
15730 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
15740 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
15750 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
15760 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
15770 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
15780 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
15790 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
157a0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
157b0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
157c0 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
157d0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
157e0 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
157f0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
15800 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
15810 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
15820 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
15830 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
15840 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15850 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
15860 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
15870 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
15880 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
15890 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
158a0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
158b0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
158c0 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
158d0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
158e0 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
158f0 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
15900 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
15910 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
15920 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15930 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
15940 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
15950 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
15960 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
15970 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
15980 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
15990 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
159a0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
159b0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
159c0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
159d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
159e0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
159f0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
15a00 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
15a10 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
15a20 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
15a30 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
15a40 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
15a50 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
15a60 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
15a70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15a80 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15a90 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
15aa0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
15ab0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
15ac0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
15ad0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
15ae0 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
15af0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
15b00 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
15b10 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
15b20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
15b30 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
15b40 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
15b50 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
15b60 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
15b70 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
15b80 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
15b90 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
15ba0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15bb0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
15bc0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
15bd0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
15be0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
15bf0 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
15c00 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
15c10 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
15c20 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
15c30 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
15c40 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
15c50 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
15c60 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
15c70 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
15c80 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
15c90 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
15ca0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
15cb0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
15cc0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
15cd0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15ce0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
15cf0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
15d00 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
15d10 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
15d20 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
15d30 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
15d40 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
15d50 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
15d60 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
15d70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
15d80 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
15d90 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
15da0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
15db0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
15dc0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
15dd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
15de0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15df0 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
15e00 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
15e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15e20 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
15e30 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
15e40 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
15e50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15e60 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
15e70 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
15e80 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
15e90 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
15ea0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
15eb0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
15ec0 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
15ed0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
15ee0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
15ef0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
15f00 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
15f10 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
15f20 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
15f30 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
15f40 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
15f50 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
15f60 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
15f70 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
15f80 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
15f90 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
15fa0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
15fb0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
15fc0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
15fd0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
15fe0 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
15ff0 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
16000 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61  ^Each entry in a
16010 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
16020 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
16030 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
16040 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
16050 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
16060 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
16070 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
16080 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
16090 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
160a0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
160b0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
160c0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
160d0 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
160e0 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
160f0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
16100 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
16110 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
16120 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
16130 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
16140 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
16150 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
16160 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
16170 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
16180 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
16190 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
161a0 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
161b0 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
161c0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
161d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
161e0 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
161f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
16200 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
16210 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53  ument.  ^As of S
16220 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
16230 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  7.7, this routin
16240 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68  es.** records th
16250 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
16260 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69  wid of both ordi
16270 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20  nary tables and 
16280 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
16290 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
162a0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
162b0 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
162c0 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
162d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
162e0 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
162f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  rned..**.** ^(If
16300 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
16310 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
16320 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
16330 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
16340 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
16350 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
16360 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
16370 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
16380 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
16390 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
163a0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
163b0 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
163c0 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
163d0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
163e0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
163f0 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
16400 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16410 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
16420 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
16430 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
16440 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
16450 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
16460 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
16470 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
16480 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
16490 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
164a0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
164b0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
164c0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
164d0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
164e0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
164f0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
16500 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
16510 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
16520 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
16530 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
16540 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
16550 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
16560 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
16570 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
16580 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
16590 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
165a0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
165b0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
165c0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
165d0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
165e0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
165f0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
16600 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
16610 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
16620 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
16630 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
16640 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
16650 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
16660 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
16670 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
16680 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
16690 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
166a0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
166b0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
166c0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
166d0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
166e0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
166f0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
16700 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
16710 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
16720 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
16730 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
16740 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
16750 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
16760 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
16770 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
16780 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
16790 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
167a0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
167b0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
167c0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
167d0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
167e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
167f0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
16800 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
16810 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
16820 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
16830 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
16840 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
16850 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
16860 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16870 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
16880 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
16890 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
168a0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
168b0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
168c0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
168d0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
168e0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
168f0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
16900 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
16910 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
16920 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
16930 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
16940 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
16950 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
16960 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
16970 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
16980 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
16990 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
169a0 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
169b0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
169c0 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
169d0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
169e0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
169f0 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
16a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16a10 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
16a20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16a30 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
16a40 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
16a50 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
16a60 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
16a70 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
16a80 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
16a90 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
16aa0 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
16ab0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
16ac0 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
16ad0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
16ae0 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
16af0 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
16b00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
16b10 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
16b20 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
16b30 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
16b40 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
16b50 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
16b60 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
16b70 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
16b80 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
16b90 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
16ba0 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
16bb0 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
16bc0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
16bd0 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
16be0 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
16bf0 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
16c00 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
16c10 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
16c20 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
16c30 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
16c40 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
16c50 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
16c60 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
16c70 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
16c80 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
16c90 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
16ca0 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
16cb0 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
16cc0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
16cd0 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
16ce0 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
16cf0 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
16d00 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
16d10 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
16d20 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
16d30 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
16d40 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
16d50 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
16d60 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
16d70 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
16d80 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
16d90 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
16da0 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
16db0 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
16dc0 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
16dd0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
16de0 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
16df0 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
16e00 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
16e10 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
16e20 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
16e30 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
16e40 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
16e50 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
16e60 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
16e70 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
16e80 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
16e90 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
16ea0 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
16eb0 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
16ec0 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
16ed0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
16ee0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
16ef0 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
16f00 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
16f10 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
16f20 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
16f30 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
16f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
16f50 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
16f60 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
16f70 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
16f80 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
16f90 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
16fa0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
16fb0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
16fc0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
16fd0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
16fe0 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
16ff0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
17000 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
17010 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17020 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
17030 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
17040 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
17050 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
17060 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
17070 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
17080 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
17090 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
170a0 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
170b0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
170c0 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
170d0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
170e0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
170f0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
17100 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
17110 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
17120 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17130 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
17140 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
17150 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
17160 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
17170 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
17180 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
17190 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
171a0 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
171b0 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
171c0 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
171d0 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
171e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
171f0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
17200 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
17210 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
17220 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
17230 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
17240 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
17250 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
17260 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
17270 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
17280 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
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 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
172b0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
172c0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
172d0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
172e0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
172f0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
17300 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
17310 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
17320 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17330 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17340 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
17350 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
17360 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
17370 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
17380 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
17390 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
173a0 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
173b0 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
173c0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
173d0 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
173e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
173f0 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
17400 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
17410 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
17420 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17430 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
17440 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
17450 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
17460 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17470 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
17480 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
17490 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
174a0 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
174b0 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
174c0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
174d0 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
174e0 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
174f0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
17500 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
17510 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
17520 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
17530 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
17540 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
17550 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
17560 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
17570 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
17580 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
17590 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
175a0 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
175b0 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
175c0 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
175d0 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
175e0 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
175f0 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
17600 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17610 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
17620 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
17630 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
17640 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
17650 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
17660 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
17670 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
17680 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
17690 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
176a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
176b0 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
176c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
176d0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
176e0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
176f0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17700 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17710 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
17720 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
17730 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
17740 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
17750 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
17760 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
17770 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
17780 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
17790 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
177a0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
177b0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
177c0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
177d0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
177e0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
177f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
17800 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
17810 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
17820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17830 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
17840 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
17850 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
17860 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
17870 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
17880 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
17890 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
178a0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
178b0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
178c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
178d0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
178e0 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
178f0 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
17900 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
17910 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
17920 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
17930 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
17940 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
17950 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
17960 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
17970 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
17980 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
17990 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
179a0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
179b0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
179c0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
179d0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
179e0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
179f0 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
17a00 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
17a10 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
17a20 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
17a30 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
17a40 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
17a50 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
17a60 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17a70 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
17a80 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
17a90 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
17aa0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
17ab0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
17ac0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
17ad0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
17ae0 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
17af0 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
17b00 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
17b10 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
17b20 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
17b30 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
17b40 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
17b50 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
17b60 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
17b70 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
17b80 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
17b90 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
17ba0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
17bb0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
17bc0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
17bd0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
17be0 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
17bf0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
17c00 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
17c10 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
17c20 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
17c30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
17c40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17c50 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
17c60 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
17c70 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
17c80 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
17c90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
17ca0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
17cb0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
17cc0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
17cd0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
17ce0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
17cf0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
17d00 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
17d10 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
17d20 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
17d30 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
17d40 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
17d50 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
17d60 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
17d70 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
17d80 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17d90 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
17da0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
17db0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
17dc0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
17dd0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
17de0 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
17df0 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
17e00 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
17e10 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17e20 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
17e30 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
17e40 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
17e50 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
17e60 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
17e70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17e80 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
17e90 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
17ea0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
17eb0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
17ec0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
17ed0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17ee0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
17ef0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
17f00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17f10 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
17f20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17f30 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
17f40 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
17f50 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
17f60 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
17f70 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
17f80 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
17f90 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17fa0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
17fb0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
17fc0 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
17fd0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
17fe0 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
17ff0 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
18000 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
18010 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
18020 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
18030 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
18040 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
18050 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
18060 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
18070 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
18080 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
18090 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
180a0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
180b0 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
180c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
180d0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
180e0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
180f0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
18100 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
18110 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
18120 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
18130 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
18140 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
18150 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
18160 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
18170 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
18180 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
18190 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
181a0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
181b0 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
181c0 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
181d0 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
181e0 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
181f0 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
18200 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
18210 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
18220 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
18230 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
18240 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
18250 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
18260 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
18270 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
18280 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
18290 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
182a0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
182b0 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
182c0 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
182d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
182e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
182f0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
18300 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
18310 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
18320 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
18330 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
18340 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
18350 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
18360 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
18370 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
18380 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
18390 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
183a0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
183b0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
183c0 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
183d0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
183e0 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
183f0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
18400 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
18410 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
18420 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
18430 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
18440 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
18450 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
18460 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
18470 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
18480 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
18490 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
184a0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
184b0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
184c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
184d0 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
184e0 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
184f0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
18500 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
18510 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
18520 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
18530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
18540 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
18550 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
18560 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
18570 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
18580 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
18590 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
185a0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
185b0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
185c0 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
185d0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
185e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
185f0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18600 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
18610 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
18620 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
18630 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
18640 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
18650 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
18660 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
18670 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
18680 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
18690 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
186a0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
186b0 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
186c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
186d0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
186e0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
186f0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
18700 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
18710 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
18720 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
18730 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
18740 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
18750 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
18760 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
18770 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
18780 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
18790 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
187a0 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
187b0 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
187c0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
187d0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
187e0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
187f0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
18800 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
18810 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
18820 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
18830 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
18840 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
18850 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
18860 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
18870 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
18880 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
18890 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
188a0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
188b0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
188c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
188d0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
188e0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
188f0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
18900 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
18910 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
18920 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
18930 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
18940 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
18950 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
18960 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
18970 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
18980 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
18990 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
189a0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
189b0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
189c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
189d0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
189e0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
189f0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
18a00 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
18a10 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
18a20 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
18a30 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
18a40 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
18a50 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
18a60 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
18a70 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
18a80 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
18a90 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
18aa0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
18ab0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
18ac0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
18ad0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
18ae0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
18af0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
18b00 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
18b10 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
18b20 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
18b30 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
18b40 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
18b50 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
18b60 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
18b70 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
18b80 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
18b90 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
18ba0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
18bb0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
18bc0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
18bd0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
18be0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
18bf0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
18c00 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
18c10 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
18c20 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
18c30 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
18c40 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
18c50 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
18c60 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
18c70 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
18c80 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
18c90 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
18ca0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
18cb0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
18cc0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
18cd0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
18ce0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
18cf0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
18d00 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
18d10 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
18d20 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
18d30 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
18d40 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
18d50 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
18d60 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
18d70 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
18d80 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
18d90 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
18da0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
18db0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
18dc0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
18dd0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
18de0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
18df0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
18e00 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
18e10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
18e20 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
18e30 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
18e40 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
18e50 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
18e60 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
18e70 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
18e80 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
18e90 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
18ea0 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
18eb0 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
18ec0 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
18ed0 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
18ee0 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
18ef0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
18f00 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
18f10 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
18f20 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
18f30 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
18f40 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
18f50 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
18f60 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
18f70 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
18f80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
18f90 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
18fa0 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
18fb0 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
18fc0 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
18fd0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
18fe0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
18ff0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
19000 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
19010 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
19020 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
19030 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
19040 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
19050 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
19060 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
19070 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
19080 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
19090 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
190a0 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
190b0 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
190c0 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
190d0 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
190e0 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
190f0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
19100 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
19110 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
19120 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
19130 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
19140 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
19150 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
19160 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
19170 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
19180 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
19190 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
191a0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
191b0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
191c0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
191d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
191e0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
191f0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
19200 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
19210 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
19220 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
19230 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
19240 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19250 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
19260 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
19270 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
19280 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
19290 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
192a0 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
192b0 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
192c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
192d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
192e0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
192f0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
19300 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
19310 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
19320 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
19330 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
19340 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
19350 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
19360 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
19370 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
19380 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
19390 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
193a0 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
193b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
193c0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
193d0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
193e0 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
193f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19400 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
19410 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
19420 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
19430 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
19440 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
19450 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
19460 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
19470 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
19480 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
19490 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
194a0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
194b0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
194c0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
194d0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
194e0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
194f0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
19500 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
19510 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
19520 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
19530 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
19540 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
19550 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
19560 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19570 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
19580 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
19590 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
195a0 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
195b0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
195c0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
195d0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
195e0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
195f0 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
19600 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
19610 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
19620 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
19630 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
19640 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
19650 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
19660 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
19670 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
19680 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
19690 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
196a0 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
196b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
196c0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
196d0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
196e0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
196f0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
19700 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
19710 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19720 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
19730 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
19740 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
19750 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
19760 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
19770 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
19780 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
19790 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
197a0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
197b0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
197c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
197d0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
197e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
197f0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
19800 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
19810 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
19820 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
19830 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
19840 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
19850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
19860 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
19870 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
19880 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
19890 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
198a0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
198b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
198c0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
198d0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
198e0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
198f0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
19900 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
19910 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
19920 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
19930 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
19940 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
19950 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
19960 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
19970 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
19980 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
19990 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
199a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
199b0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
199c0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
199d0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
199e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
199f0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
19a00 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
19a10 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
19a20 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
19a30 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
19a40 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
19a50 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
19a60 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
19a70 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
19a80 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
19a90 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
19aa0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
19ab0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
19ac0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
19ad0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
19ae0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
19af0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
19b00 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
19b10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
19b20 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
19b30 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
19b40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
19b50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
19b60 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
19b70 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
19b80 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
19b90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19ba0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
19bb0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
19bc0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
19bd0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
19be0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
19bf0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
19c00 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
19c10 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
19c20 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
19c30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
19c40 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
19c50 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
19c60 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
19c70 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
19c80 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
19c90 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
19ca0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
19cb0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
19cc0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
19cd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19ce0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
19cf0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
19d00 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
19d10 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
19d20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
19d30 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
19d40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
19d50 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
19d60 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
19d70 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
19d80 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
19d90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
19da0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
19db0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
19dc0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
19dd0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
19de0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
19df0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
19e00 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
19e10 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
19e20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
19e30 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19e40 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
19e50 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19e60 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
19e70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19e80 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
19e90 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
19ea0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
19eb0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
19ec0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19ed0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
19ee0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19ef0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
19f00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19f10 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
19f20 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19f30 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
19f40 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
19f50 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
19f60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19f70 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
19f80 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
19f90 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
19fa0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
19fb0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
19fc0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
19fd0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
19fe0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
19ff0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1a000 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1a010 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1a020 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1a030 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1a040 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1a050 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1a060 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1a070 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1a080 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1a090 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1a0a0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1a0b0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1a0c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1a0d0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1a0e0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1a0f0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1a100 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1a110 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1a120 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1a130 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1a140 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1a150 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a160 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1a170 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1a180 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1a190 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1a1a0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1a1b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1a1c0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1a1d0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1a1e0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1a1f0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1a200 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1a210 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1a220 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1a230 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1a240 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1a250 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1a260 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1a270 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1a280 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1a290 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1a2a0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1a2b0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1a2c0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1a2d0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1a2e0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1a2f0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1a300 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1a310 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1a320 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1a330 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1a340 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1a350 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1a360 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1a370 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1a380 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1a390 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1a3a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1a3b0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1a3c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1a3d0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1a3e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1a3f0 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1a400 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1a410 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1a420 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1a430 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1a440 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1a450 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1a460 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1a470 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1a480 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1a490 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1a4a0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1a4b0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1a4c0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1a4d0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1a4e0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1a4f0 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1a500 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1a510 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1a520 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1a530 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1a540 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1a550 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1a560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a570 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1a580 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1a590 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1a5a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1a5b0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1a5c0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1a5d0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1a5e0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1a5f0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1a600 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1a610 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1a620 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1a630 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1a640 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1a650 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1a660 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1a670 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a680 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1a690 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1a6a0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1a6b0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1a6c0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1a6d0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1a6e0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1a6f0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1a700 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1a710 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1a720 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1a730 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1a740 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1a750 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1a760 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1a770 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1a780 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1a790 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1a7a0 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1a7b0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1a7c0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1a7d0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1a7e0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1a7f0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1a800 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1a810 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1a820 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1a830 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1a840 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1a850 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1a860 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1a870 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1a880 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1a890 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1a8a0 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1a8b0 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1a8c0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1a8d0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1a8e0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1a8f0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1a900 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1a910 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1a920 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1a930 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1a940 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1a950 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1a960 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1a970 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1a980 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1a990 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1a9a0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1a9b0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1a9c0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1a9d0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1a9e0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1a9f0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1aa00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1aa10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1aa20 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1aa30 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1aa40 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1aa50 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1aa60 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1aa70 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1aa80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1aa90 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1aaa0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1aab0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1aac0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1aad0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1aae0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1aaf0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1ab00 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1ab10 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1ab20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1ab30 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1ab40 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1ab50 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1ab60 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1ab70 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1ab80 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1ab90 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1aba0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1abb0 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1abc0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1abd0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1abe0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1abf0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1ac00 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1ac10 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1ac20 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1ac30 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1ac40 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1ac50 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1ac60 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1ac70 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1ac80 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1ac90 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1aca0 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1acb0 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
1acc0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1acd0 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1ace0 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1acf0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1ad00 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1ad10 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1ad20 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1ad30 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1ad40 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1ad50 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1ad60 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1ad70 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1ad80 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1ad90 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1ada0 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1adb0 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1adc0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1add0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1ade0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1adf0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1ae00 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1ae10 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1ae20 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1ae30 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1ae40 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1ae50 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ae60 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1ae70 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1ae80 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1ae90 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1aea0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1aeb0 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1aec0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1aed0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1aee0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1aef0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1af00 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1af10 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1af20 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1af30 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1af40 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1af50 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1af60 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1af70 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1af80 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1af90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1afa0 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1afb0 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1afc0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1afd0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1afe0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1aff0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1b000 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1b010 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1b020 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b030 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1b040 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1b050 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1b060 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b070 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1b080 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1b090 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1b0a0 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1b0b0 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1b0c0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1b0d0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1b0e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b0f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1b100 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1b110 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1b120 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1b130 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b140 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1b150 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1b160 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1b170 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1b180 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1b190 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1b1a0 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1b1b0 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1b1c0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1b1d0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1b1e0 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1b1f0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1b200 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1b210 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1b220 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1b230 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1b240 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1b250 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1b260 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1b270 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1b280 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1b290 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1b2a0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1b2b0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1b2c0 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1b2d0 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1b2e0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1b2f0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1b300 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b310 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1b320 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b330 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1b340 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1b350 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1b360 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1b370 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1b380 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1b390 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1b3a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b3b0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1b3c0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1b3d0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1b3e0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1b3f0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1b400 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1b410 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1b420 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1b430 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1b440 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1b450 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1b460 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1b470 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1b480 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1b490 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1b4a0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1b4b0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1b4c0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1b4d0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1b4e0 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53  t string.)^.*/.S
1b4f0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1b500 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b510 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1b520 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1b530 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1b540 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1b550 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54   va_list);.SQLIT
1b560 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1b570 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1b580 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1b590 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  r*, ...);.SQLITE
1b5a0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1b5b0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1b5c0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1b5d0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1b5e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1b5f0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1b600 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1b610 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1b620 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1b630 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1b640 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1b650 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1b660 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1b670 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1b680 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1b690 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1b6a0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1b6b0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1b6c0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1b6d0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1b6e0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1b6f0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1b700 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1b710 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1b720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b730 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1b740 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1b750 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1b760 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1b770 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1b780 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1b790 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1b7a0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1b7b0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1b7c0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1b7d0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1b7e0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1b7f0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1b800 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1b810 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1b820 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b830 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1b840 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1b850 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1b860 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1b870 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
1b880 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1b890 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1b8a0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1b8b0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1b8c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1b8d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b8e0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1b8f0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1b900 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1b910 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1b920 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1b930 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1b940 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1b950 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1b960 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1b970 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1b980 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1b990 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1b9a0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1b9b0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1b9c0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1b9d0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1b9e0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1b9f0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1ba00 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1ba10 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1ba20 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1ba30 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1ba40 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1ba50 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1ba60 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1ba70 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1ba80 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1ba90 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1baa0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1bab0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1bac0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1bad0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1bae0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1baf0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1bb00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1bb10 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1bb20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
1bb30 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1bb40 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1bb50 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1bb60 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
1bb70 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
1bb80 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1bb90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1bba0 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
1bbb0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1bbc0 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
1bbd0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1bbe0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
1bbf0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1bc00 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1bc10 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
1bc20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1bc30 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1bc40 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1bc50 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1bc60 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
1bc70 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1bc80 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1bc90 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1bca0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
1bcb0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1bcc0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
1bcd0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1bce0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1bcf0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1bd00 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1bd10 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1bd20 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
1bd30 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
1bd40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1bd50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1bd60 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1bd70 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1bd80 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1bd90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1bda0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1bdb0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1bdc0 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1bdd0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1bde0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1bdf0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1be00 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1be10 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1be20 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1be30 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1be40 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1be50 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1be60 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1be70 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1be80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1be90 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1bea0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1beb0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1bec0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1bed0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1bee0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1bef0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1bf00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1bf10 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1bf20 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1bf30 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1bf40 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1bf50 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1bf60 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1bf70 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1bf80 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1bf90 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1bfa0 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1bfb0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1bfc0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1bfd0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1bfe0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1bff0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1c000 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1c010 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1c020 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1c030 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1c040 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1c050 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1c060 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1c070 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1c080 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1c090 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1c0a0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1c0b0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1c0c0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1c0d0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1c0e0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1c0f0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1c100 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1c110 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1c120 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1c130 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1c140 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1c150 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1c160 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1c170 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1c180 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1c190 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1c1a0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1c1b0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1c1c0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1c1d0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1c1e0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1c1f0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1c200 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1c210 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1c220 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1c230 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1c240 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1c250 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1c260 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1c270 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1c280 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1c290 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1c2a0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1c2b0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1c2c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1c2d0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1c2e0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1c2f0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1c300 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1c310 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1c320 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1c330 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1c340 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1c350 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1c360 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1c370 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1c380 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1c390 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1c3a0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1c3b0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1c3c0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1c3d0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1c3e0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1c3f0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1c400 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c410 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1c420 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d   void *sqlite3_m
1c430 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49  alloc(int);.SQLI
1c440 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1c450 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1c460 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
1c470 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1c480 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
1c490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c4a0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1c4b0 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1c4c0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1c4d0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1c4e0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1c4f0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1c500 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1c510 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1c520 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c530 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1c540 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1c550 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1c560 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1c570 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c580 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1c590 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1c5a0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1c5b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1c5c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1c5d0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1c5e0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1c5f0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1c600 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1c610 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1c620 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c630 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1c640 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1c650 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1c660 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c670 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1c680 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1c690 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1c6a0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1c6b0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1c6c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1c6d0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1c6e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c6f0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1c700 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1c710 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1c720 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1c730 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1c740 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1c750 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1c760 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1c770 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1c780 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1c790 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1c7a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1c7b0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1c7c0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1c7d0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1c7e0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1c7f0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1c800 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c810 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1c820 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1c830 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1c840 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c850 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1c860 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1c870 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1c880 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1c890 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1c8a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1c8b0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1c8c0 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54   reset..*/.SQLIT
1c8d0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
1c8e0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1c8f0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53  ry_used(void);.S
1c900 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1c910 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1c920 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1c930 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
1c940 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c950 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
1c960 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
1c970 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
1c980 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
1c990 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
1c9a0 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
1c9b0 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
1c9c0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
1c9d0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
1c9e0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
1c9f0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
1ca00 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
1ca10 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
1ca20 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
1ca30 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
1ca40 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
1ca50 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
1ca60 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
1ca70 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
1ca80 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
1ca90 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
1caa0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
1cab0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
1cac0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
1cad0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
1cae0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
1caf0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1cb00 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
1cb10 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
1cb20 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
1cb30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1cb40 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
1cb50 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
1cb60 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
1cb70 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
1cb80 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
1cb90 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
1cba0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1cbb0 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
1cbc0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1cbd0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
1cbe0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1cbf0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1cc00 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
1cc10 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
1cc20 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1cc30 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1cc40 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1cc50 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1cc60 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1cc70 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1cc80 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1cc90 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
1cca0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
1ccb0 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1ccc0 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1ccd0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1cce0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1ccf0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1cd00 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1cd10 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1cd20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cd30 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1cd40 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1cd50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1cd60 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1cd70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1cd80 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1cd90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1cda0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1cdb0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1cdc0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1cdd0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1cde0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1cdf0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1ce00 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1ce10 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1ce20 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1ce30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1ce40 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1ce50 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1ce60 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1ce70 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1ce80 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1ce90 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1cea0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1ceb0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1cec0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1ced0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1cee0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1cef0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1cf00 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1cf10 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1cf20 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1cf30 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1cf40 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1cf50 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1cf60 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1cf70 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1cf80 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1cf90 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1cfa0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1cfb0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1cfc0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1cfd0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1cfe0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1cff0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1d000 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1d010 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1d020 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1d030 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1d040 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1d050 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1d060 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1d070 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1d080 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1d090 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d0a0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1d0b0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1d0c0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1d0d0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1d0e0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1d0f0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1d100 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d110 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1d120 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1d130 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1d140 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1d150 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1d160 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1d170 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1d180 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d190 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1d1a0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1d1b0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1d1c0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1d1d0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1d1e0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1d1f0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1d200 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1d210 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1d220 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1d230 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d240 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1d250 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1d260 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1d270 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1d280 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1d290 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1d2a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1d2b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1d2c0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1d2d0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1d2e0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1d2f0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1d300 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1d310 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1d320 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1d330 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1d340 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1d350 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1d360 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1d370 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1d380 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1d390 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1d3a0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1d3b0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1d3c0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1d3d0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1d3e0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1d3f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d400 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1d410 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1d420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d430 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1d440 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1d450 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1d460 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1d470 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1d480 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1d490 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1d4a0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1d4b0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1d4c0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1d4d0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1d4e0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1d4f0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1d500 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1d510 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1d520 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1d530 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1d540 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1d550 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1d560 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1d570 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1d580 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1d590 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1d5a0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1d5b0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1d5c0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1d5d0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1d5e0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1d5f0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1d600 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1d610 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1d620 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1d630 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1d640 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1d650 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1d660 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1d670 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1d680 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1d690 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1d6a0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1d6b0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1d6c0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1d6d0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1d6e0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1d6f0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1d700 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1d710 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1d720 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1d730 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1d740 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1d750 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1d760 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1d770 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1d780 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1d790 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1d7a0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1d7b0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1d7c0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1d7d0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1d7e0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1d7f0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1d800 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1d810 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1d820 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1d830 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1d840 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1d850 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1d860 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1d870 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1d880 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1d890 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1d8a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1d8b0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1d8c0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1d8d0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1d8e0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1d8f0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1d900 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1d910 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1d920 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1d930 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1d940 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1d950 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1d960 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1d970 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1d980 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1d990 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1d9a0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1d9b0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1d9c0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1d9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d9e0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1d9f0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1da00 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1da10 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1da20 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1da30 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1da40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1da50 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1da60 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1da70 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1da80 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1da90 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1daa0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1dab0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1dac0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1dad0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1dae0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1daf0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1db00 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1db10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1db20 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1db30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1db40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1db50 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1db60 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1db70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1db80 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1db90 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1dba0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1dbb0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1dbc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1dbd0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1dbe0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1dbf0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1dc00 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1dc10 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1dc20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1dc30 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1dc40 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1dc50 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1dc60 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1dc70 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1dc80 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1dc90 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1dca0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1dcb0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1dcc0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1dcd0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1dce0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1dcf0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1dd00 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1dd10 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1dd20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1dd30 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1dd40 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1dd50 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1dd60 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1dd70 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1dd80 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1dd90 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1dda0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1ddb0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1ddc0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1ddd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dde0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1ddf0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1de00 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1de10 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
1de20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74   int sqlite3_set
1de30 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1de40 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1de50 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1de60 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1de70 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1de80 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1de90 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1dea0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1deb0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1dec0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1ded0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1dee0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1def0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1df00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1df10 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1df20 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1df30 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1df40 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1df50 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1df60 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1df70 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1df80 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1df90 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1dfa0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1dfb0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1dfc0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1dfd0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1dfe0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1dff0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1e000 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1e010 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1e020 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1e030 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1e040 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1e050 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1e060 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1e070 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1e080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1e090 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1e0a0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1e0b0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1e0c0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1e0d0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1e0e0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1e0f0 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1e100 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1e110 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1e120 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1e130 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1e140 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1e150 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1e160 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1e170 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1e180 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1e190 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1e1a0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1e1b0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1e1c0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1e1d0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1e1e0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1e1f0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1e200 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1e210 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1e220 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1e230 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1e240 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1e250 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1e260 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1e270 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1e280 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1e290 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1e2a0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1e2b0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1e2c0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1e2d0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1e2e0 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1e2f0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1e300 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1e310 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1e320 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1e330 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1e340 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1e350 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1e360 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1e370 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1e380 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1e390 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1e3a0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1e3b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1e3c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1e3d0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1e3e0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1e3f0 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1e400 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1e410 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1e420 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e430 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1e440 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1e450 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1e460 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1e470 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1e480 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1e490 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1e4a0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1e4b0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1e4c0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1e4d0 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1e4e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e4f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e500 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1e510 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1e520 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1e530 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e540 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1e550 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1e560 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1e570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e580 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e590 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1e5a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e5b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e5c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e5d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1e5e0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1e5f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1e600 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e610 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e620 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1e630 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1e640 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e650 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e670 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1e680 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1e690 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1e6a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e6b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e6c0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1e6d0 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1e6e0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1e6f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e710 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1e720 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1e730 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1e740 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e760 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1e770 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1e780 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1e790 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e7a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e7b0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1e7c0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1e7d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e7e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e7f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e800 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1e810 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1e820 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1e830 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e850 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1e860 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1e870 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e8a0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1e8b0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1e8c0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e8d0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e8e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e8f0 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1e900 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1e910 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e920 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e930 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e940 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1e950 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1e960 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1e970 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e980 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e990 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1e9a0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1e9b0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1e9c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e9d0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1e9e0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1e9f0 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1ea00 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1ea10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ea20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1ea30 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1ea40 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1ea50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ea60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ea70 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1ea80 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1ea90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1eaa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1eab0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eac0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1ead0 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1eae0 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1eaf0 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1eb00 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1eb10 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1eb20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1eb30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1eb40 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1eb50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eb60 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1eb70 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1eb80 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1eb90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1eba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ebb0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1ebc0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1ebd0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1ebe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ebf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ec00 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1ec10 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1ec20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ec30 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1ec40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ec50 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1ec60 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1ec70 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1ec80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ec90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eca0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1ecb0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1ecc0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1ecd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ece0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ecf0 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1ed00 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1ed10 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1ed20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ed30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1ed40 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1ed50 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1ed60 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1ed70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ed80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1ed90 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1eda0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1edb0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1edc0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1edd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ede0 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1edf0 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1ee00 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1ee10 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1ee20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ee30 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1ee40 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1ee50 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1ee60 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1ee70 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1ee80 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1ee90 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1eea0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1eeb0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1eec0 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1eed0 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1eee0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1eef0 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1ef00 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1ef10 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1ef20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1ef30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1ef40 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1ef50 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1ef60 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1ef70 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1ef80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1ef90 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1efa0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1efb0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1efc0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1efd0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1efe0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1eff0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1f000 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1f010 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1f020 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1f030 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1f040 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1f050 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1f060 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1f070 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1f080 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1f090 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1f0a0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1f0b0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1f0c0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1f0d0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1f0e0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1f0f0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1f100 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1f110 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1f120 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1f130 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1f140 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1f150 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1f160 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1f170 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1f180 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1f190 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1f1a0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1f1b0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1f1c0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1f1d0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
1f1e0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
1f1f0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
1f200 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
1f210 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
1f220 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
1f230 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
1f240 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
1f250 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
1f260 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
1f270 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1f280 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1f290 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1f2a0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
1f2b0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
1f2c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1f2d0 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
1f2e0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1f2f0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1f300 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1f310 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1f320 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1f330 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1f340 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1f350 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1f360 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
1f370 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
1f380 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
1f390 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
1f3a0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
1f3b0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1f3c0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
1f3d0 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
1f3e0 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
1f3f0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
1f400 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
1f410 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
1f420 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
1f430 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
1f440 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
1f450 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
1f460 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
1f470 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
1f480 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
1f490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
1f4a0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
1f4b0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
1f4c0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1f4d0 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1f4e0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1f4f0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1f500 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
1f510 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1f520 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
1f530 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
1f540 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
1f550 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
1f560 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45  _API SQLITE_EXPE
1f570 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1f580 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1f590 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1f5a0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1f5b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1f5c0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1f5d0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1f5e0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1f5f0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1f600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f610 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1f620 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
1f630 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
1f640 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
1f650 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
1f660 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1f670 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1f680 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
1f690 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
1f6a0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
1f6b0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
1f6c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1f6d0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
1f6e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
1f6f0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1f700 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1f710 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1f720 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1f730 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1f740 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
1f750 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
1f760 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
1f770 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
1f780 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
1f790 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f7a0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
1f7b0 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
1f7c0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
1f7d0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
1f7e0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
1f7f0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
1f800 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
1f810 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
1f820 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
1f830 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
1f840 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
1f850 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
1f860 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
1f870 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
1f880 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
1f890 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
1f8a0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
1f8b0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
1f8c0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
1f8d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
1f8e0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
1f8f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1f900 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
1f910 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
1f920 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
1f930 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
1f940 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1f950 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
1f960 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
1f970 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
1f980 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
1f990 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
1f9a0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
1f9b0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1f9c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1f9d0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1f9e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1f9f0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1fa00 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1fa10 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1fa20 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1fa30 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1fa40 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1fa50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1fa60 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1fa70 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1fa80 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1fa90 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1faa0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1fab0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1fac0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
1fad0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
1fae0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1faf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1fb00 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1fb10 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1fb20 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1fb30 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1fb40 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1fb50 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1fb60 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1fb70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1fb80 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1fb90 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1fba0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1fbb0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1fbc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fbd0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1fbe0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1fbf0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
1fc00 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
1fc10 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1fc20 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
1fc30 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
1fc40 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1fc50 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
1fc60 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1fc70 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1fc80 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1fc90 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1fca0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
1fcb0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1fcc0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
1fcd0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
1fce0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
1fcf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1fd00 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1fd10 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1fd20 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1fd30 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1fd40 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1fd50 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1fd60 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1fd70 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1fd80 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1fd90 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1fda0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1fdb0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1fdc0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1fdd0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1fde0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1fdf0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1fe00 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
1fe10 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1fe20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1fe30 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1fe40 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1fe50 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1fe60 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1fe70 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1fe80 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
1fe90 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1fea0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1feb0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1fec0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1fed0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1fee0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1fef0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1ff00 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
1ff10 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
1ff20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
1ff30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1ff40 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1ff50 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
1ff60 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1ff70 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1ff80 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1ff90 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1ffa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ffb0 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1ffc0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1ffd0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1ffe0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1fff0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
20000 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
20010 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
20020 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
20030 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
20040 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
20050 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
20060 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
20070 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
20080 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
20090 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
200a0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
200b0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
200c0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
200d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
200e0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
200f0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
20100 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
20110 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
20120 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
20130 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
20140 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
20150 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
20160 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
20170 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
20180 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
20190 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
201a0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
201b0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
201c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
201d0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
201e0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
201f0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
20200 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
20210 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
20220 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
20230 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
20240 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
20250 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20260 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
20270 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
20280 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
20290 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
202a0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
202b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
202c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
202d0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
202e0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
202f0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
20300 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
20310 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
20320 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
20330 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
20340 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20350 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
20360 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
20370 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
20380 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
20390 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
203a0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
203b0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
203c0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
203d0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
203e0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
203f0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
20400 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
20410 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
20420 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
20430 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
20440 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
20450 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
20460 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
20470 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
20480 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
20490 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
204a0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
204b0 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
204c0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
204d0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
204e0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
204f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
20500 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
20510 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
20520 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
20530 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
20540 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
20550 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
20560 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
20570 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
20580 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
20590 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
205a0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
205b0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
205c0 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
205d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
205e0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
205f0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
20600 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
20610 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
20620 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
20630 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
20640 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
20650 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
20660 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
20670 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
20680 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
20690 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
206a0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
206b0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
206c0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
206d0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
206e0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
206f0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
20700 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
20710 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
20720 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
20730 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
20740 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
20750 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
20760 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
20770 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
20780 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
20790 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
207a0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
207b0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
207c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
207d0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
207e0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
207f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
20800 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
20810 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
20820 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
20830 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
20840 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
20850 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
20860 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
20870 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
20880 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
20890 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
208a0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
208b0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
208c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
208d0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
208e0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
208f0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
20900 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
20910 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
20920 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
20930 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
20940 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
20950 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
20960 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
20970 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
20980 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
20990 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
209a0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
209b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
209c0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
209d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
209e0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
209f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
20a00 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
20a10 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
20a20 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
20a30 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
20a40 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
20a50 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
20a60 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
20a70 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
20a80 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
20a90 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
20aa0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
20ab0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
20ac0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
20ad0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20ae0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
20af0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
20b00 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
20b10 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
20b20 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
20b30 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
20b40 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
20b50 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
20b60 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
20b70 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
20b80 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
20b90 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
20ba0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
20bb0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
20bc0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
20bd0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
20be0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
20bf0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
20c00 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
20c10 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
20c20 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
20c30 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
20c40 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
20c50 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
20c60 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
20c70 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
20c80 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
20c90 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
20ca0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
20cb0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
20cc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20cd0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
20ce0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
20cf0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
20d00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
20d10 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
20d20 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
20d30 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
20d40 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
20d50 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
20d60 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
20d70 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
20d80 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
20d90 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
20da0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
20db0 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
20dc0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
20dd0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
20de0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
20df0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
20e00 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
20e10 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
20e20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
20e30 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
20e40 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
20e50 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
20e60 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
20e70 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
20e80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
20e90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
20ea0 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
20eb0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
20ec0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
20ed0 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
20ee0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
20ef0 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
20f00 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
20f10 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
20f20 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
20f30 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
20f40 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
20f50 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
20f60 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
20f70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
20f80 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
20f90 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
20fa0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
20fb0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
20fc0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
20fd0 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
20fe0 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
20ff0 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
21000 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
21010 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
21020 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
21030 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
21040 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
21050 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
21060 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
21070 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
21080 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
21090 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
210a0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
210b0 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
210c0 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
210d0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
210e0 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
210f0 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
21100 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
21110 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
21120 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
21130 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21140 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
21150 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
21160 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
21170 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
21180 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
21190 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
211a0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
211b0 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
211c0 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
211d0 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
211e0 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
211f0 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
21200 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
21210 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
21220 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
21230 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
21240 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
21250 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
21260 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c  .** ^On windows,
21270 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
21280 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
21290 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
212a0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
212b0 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
212c0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )..**.** [[core 
212d0 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
212e0 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
212f0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
21300 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
21310 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
21320 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
21330 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
21340 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
21350 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
21360 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
21370 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
21380 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
21390 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
213a0 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ee query paramet
213b0 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
213c0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
213d0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
213e0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
213f0 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
21400 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
21410 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
21420 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
21430 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
21440 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
21450 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
21460 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
21470 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
21480 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
21490 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
214a0 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
214b0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
214c0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
214d0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
214e0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
214f0 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
21500 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
21510 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
21520 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
21530 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
21540 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
21550 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
21560 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
21570 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
21580 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
21590 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
215a0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
215b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
215c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
215d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
215e0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
215f0 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
21600 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
21610 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
21620 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
21630 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
21640 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
21650 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
21660 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
21670 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
21680 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
21690 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
216a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
216b0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
216c0 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
216d0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
216e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
216f0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
21700 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
21710 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
21720 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
21730 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21740 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
21750 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
21760 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
21770 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21780 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21790 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
217a0 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
217b0 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
217c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
217d0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
217e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
217f0 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
21800 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
21810 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
21820 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
21830 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
21840 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
21850 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
21860 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
21870 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
21880 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
21890 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
218a0 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
218b0 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
218c0 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
218d0 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
218e0 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
218f0 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
21900 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
21910 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
21920 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
21930 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
21940 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
21950 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
21960 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
21970 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
21980 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
21990 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
219a0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
219b0 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
219c0 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
219d0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
219e0 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
219f0 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
21a00 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
21a10 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
21a20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
21a30 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
21a40 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
21a50 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
21a60 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
21a70 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
21a80 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
21a90 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
21aa0 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
21ab0 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
21ac0 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
21ad0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
21ae0 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
21af0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21b00 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
21b10 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
21b20 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
21b30 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
21b40 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
21b50 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
21b60 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
21b70 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
21b80 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
21b90 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
21ba0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
21bb0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
21bc0 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
21bd0 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
21be0 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ul>.**.**
21bf0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
21c00 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
21c10 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
21c20 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
21c30 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
21c40 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
21c50 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
21c60 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
21c70 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
21c80 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
21c90 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
21ca0 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
21cb0 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
21cc0 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
21cd0 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
21ce0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
21cf0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
21d00 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
21d10 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
21d20 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
21d30 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
21d40 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
21d50 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
21d60 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
21d70 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
21d80 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
21d90 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
21da0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
21db0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
21dc0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
21dd0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
21de0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
21df0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
21e00 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
21e10 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
21e20 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
21e30 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
21e40 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
21e50 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
21e60 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
21e70 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
21e80 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
21e90 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
21ea0 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
21eb0 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
21ec0 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
21ed0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
21ee0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
21ef0 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
21f00 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
21f10 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
21f20 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
21f30 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
21f40 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
21f50 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
21f60 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
21f70 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
21f80 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
21f90 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
21fa0 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
21fb0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
21fc0 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
21fd0 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
21fe0 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
21ff0 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
22000 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
22010 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
22020 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
22030 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
22040 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
22050 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
22060 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
22070 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
22080 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22090 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
220a0 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
220b0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
220c0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
220d0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
220e0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
220f0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
22100 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
22110 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
22120 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
22130 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
22140 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
22150 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
22160 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
22170 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
22180 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
22190 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
221a0 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e  unix-nolock <td>
221b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
221c0 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
221d0 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
221e0 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
221f0 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a   "unix-nolock"..
22200 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
22210 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
22220 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
22230 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
22240 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
22250 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
22260 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
22270 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
22280 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
22290 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
222a0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
222b0 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
222c0 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
222d0 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
222e0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
222f0 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
22300 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
22310 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
22320 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
22330 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
22340 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
22350 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
22360 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
22370 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
22380 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
22390 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
223a0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
223b0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
223c0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
223d0 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
223e0 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
223f0 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
22400 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
22410 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
22420 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
22430 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
22440 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
22450 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
22460 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
22470 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
22480 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
22490 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
224a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
224b0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
224c0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
224d0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
224e0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
224f0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
22500 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
22510 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
22520 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
22530 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
22540 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
22550 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
22560 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
22570 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
22580 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
22590 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
225a0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
225b0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
225c0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
225d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
225e0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
225f0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
22600 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
22610 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
22620 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
22630 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
22640 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
22650 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
22660 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
22670 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
22680 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
22690 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
226a0 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
226b0 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
226c0 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
226d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
226e0 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
226f0 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c  irectory].*/.SQL
22700 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
22710 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
22720 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
22730 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
22740 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
22750 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
22760 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
22770 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
22780 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c  handle */.);.SQL
22790 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
227a0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
227b0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
227c0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
227d0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
227e0 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
227f0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
22800 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
22810 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
22820 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
22830 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
22840 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
22850 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
22860 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
22870 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
22880 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
22890 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
228a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
228b0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
228c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
228d0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
228e0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
228f0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
22900 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
22910 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22920 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
22930 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
22940 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
22950 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
22960 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
22970 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
22980 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
22990 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
229a0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
229b0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
229c0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
229d0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
229e0 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
229f0 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
22a00 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
22a10 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
22a20 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
22a30 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
22a40 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
22a50 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
22a60 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
22a70 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
22a80 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
22a90 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
22aa0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
22ab0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
22ac0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
22ad0 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
22ae0 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
22af0 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
22b00 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22b10 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
22b20 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
22b30 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
22b40 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
22b50 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
22b60 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
22b70 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
22b80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
22b90 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
22ba0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
22bb0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
22bc0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
22bd0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
22be0 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
22bf0 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
22c00 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
22c10 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
22c20 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
22c30 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
22c40 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
22c50 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
22c60 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
22c70 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
22c80 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
22c90 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
22ca0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
22cb0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
22cc0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
22cd0 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
22ce0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
22cf0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
22d00 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
22d10 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
22d20 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
22d30 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
22d40 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
22d50 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
22d60 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
22d70 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
22d80 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
22d90 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
22da0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
22db0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
22dc0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
22dd0 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
22de0 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
22df0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
22e00 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
22e10 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
22e20 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
22e30 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
22e40 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
22e50 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
22e60 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
22e70 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
22e80 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
22e90 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
22ea0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
22eb0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
22ec0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
22ed0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
22ee0 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
22ef0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
22f00 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
22f10 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
22f20 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
22f30 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
22f40 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
22f50 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
22f60 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
22f70 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
22f80 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
22f90 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
22fa0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
22fb0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
22fc0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
22fd0 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
22fe0 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
22ff0 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
23000 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23010 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
23020 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
23030 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
23040 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
23050 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
23060 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
23070 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
23080 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
23090 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
230a0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
230b0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
230c0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
230d0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
230e0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
230f0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
23100 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
23110 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49  sirable..*/.SQLI
23120 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
23130 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
23140 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
23150 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
23160 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
23170 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  am);.SQLITE_API 
23180 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
23190 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
231a0 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
231b0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
231c0 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51  nt bDefault);.SQ
231d0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
231e0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
231f0 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
23200 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
23210 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
23220 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
23230 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
23240 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
23250 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
23260 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
23270 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
23280 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
23290 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
232a0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
232b0 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
232c0 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
232d0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
232e0 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
232f0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
23300 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
23310 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
23320 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
23330 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
23340 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
23350 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
23360 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
23370 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
23380 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54  s undefined.  ^T
23390 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
233a0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
233b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
233c0 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
233d0 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
233e0 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
233f0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
23400 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
23410 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
23420 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
23430 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
23440 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
23450 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
23460 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
23470 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
23480 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
23490 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
234a0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
234b0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
234c0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
234d0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
234e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
234f0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
23500 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
23510 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
23520 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
23530 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
23540 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
23550 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
23560 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
23570 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
23580 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
23590 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
235a0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
235b0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
235c0 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
235d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
235e0 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
235f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
23600 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
23610 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
23620 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
23630 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
23640 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
23650 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
23660 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
23670 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
23680 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
23690 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
236a0 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
236b0 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
236c0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
236d0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
236e0 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
236f0 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
23700 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
23710 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
23720 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
23730 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
23740 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
23750 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
23760 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
23770 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
23780 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
23790 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
237a0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
237b0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
237c0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
237d0 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
237e0 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
237f0 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
23800 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
23810 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
23820 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
23830 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
23840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23850 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
23860 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
23870 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
23880 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
23890 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
238a0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
238b0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
238c0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
238d0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
238e0 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
238f0 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
23900 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
23910 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
23920 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
23930 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
23940 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
23950 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
23960 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
23970 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
23980 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
23990 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
239a0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
239b0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
239c0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
239d0 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
239e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
239f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
23a00 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
23a10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
23a20 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
23a30 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
23a40 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
23a50 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
23a60 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
23a70 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
23a80 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
23a90 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
23aa0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
23ab0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
23ac0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
23ad0 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
23ae0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
23af0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
23b00 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
23b10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
23b20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
23b30 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
23b40 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
23b50 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
23b60 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
23b70 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
23b80 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
23b90 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
23ba0 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
23bb0 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
23bc0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
23bd0 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
23be0 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
23bf0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
23c00 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
23c10 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
23c20 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
23c30 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
23c40 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
23c50 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
23c60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23c70 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
23c80 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
23c90 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
23ca0 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
23cb0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
23cc0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
23cd0 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
23ce0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
23cf0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
23d00 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
23d10 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
23d20 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
23d30 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
23d40 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
23d50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23d60 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
23d70 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
23d80 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
23d90 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
23da0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
23db0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
23dc0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
23dd0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
23de0 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
23df0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
23e00 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
23e10 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
23e20 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
23e30 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
23e40 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
23e50 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
23e60 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
23e70 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
23e80 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  mits.**.** ^(Thi
23e90 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
23ea0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
23eb0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
23ec0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
23ed0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
23ee0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
23ef0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
23f00 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
23f10 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
23f20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
23f30 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
23f40 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
23f50 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
23f60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
23f70 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
23f80 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
23f90 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
23fa0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
23fb0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
23fc0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
23fd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
23fe0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
23ff0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
24000 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
24010 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
24020 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
24030 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
24040 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
24050 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
24060 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
24070 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
24080 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
24090 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
240a0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
240b0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
240c0 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
240d0 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
240e0 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
240f0 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
24100 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
24110 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
24120 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
24130 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
24140 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
24150 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
24160 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
24170 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
24180 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
24190 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
241a0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
241b0 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
241c0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
241d0 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
241e0 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
241f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
24200 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
24210 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
24220 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
24230 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
24240 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
24250 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
24260 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
24270 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
24280 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
24290 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
242a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
242b0 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
242c0 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
242d0 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
242e0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
242f0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
24300 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
24310 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
24320 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
24330 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
24340 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
24350 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
24360 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
24370 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
24380 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
24390 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
243a0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
243b0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
243c0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
243d0 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
243e0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
243f0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
24400 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
24410 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
24420 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
24430 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
24440 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
24450 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
24460 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
24470 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
24480 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
24490 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
244a0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
244b0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
244c0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
244d0 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
244e0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
244f0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
24500 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
24510 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
24520 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
24530 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
24540 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
24550 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
24560 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
24570 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
24580 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
24590 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
245a0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
245b0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
245c0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
245d0 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
245e0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
245f0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
24600 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
24610 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
24620 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
24630 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
24640 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
24650 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
24660 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
24670 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
24680 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
24690 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
246a0 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
246b0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
246c0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
246d0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
246e0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
246f0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
24700 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
24710 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
24720 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
24730 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
24740 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
24750 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
24760 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
24770 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
24780 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
24790 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
247a0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
247b0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
247c0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
247d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
247e0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
247f0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
24800 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24810 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
24820 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
24830 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
24840 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
24850 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24860 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
24870 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24880 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
24890 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
248a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
248b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
248c0 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
248d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
248e0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
248f0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24900 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
24910 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24920 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
24930 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
24940 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
24950 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
24960 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
24970 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
24980 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
24990 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
249a0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
249b0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
249c0 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
249d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
249e0 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
249f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24a00 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
24a10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24a20 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
24a30 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
24a40 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
24a50 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24a60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
24a70 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
24a80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
24a90 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
24aa0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24ab0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
24ac0 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
24ad0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
24ae0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
24af0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
24b00 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
24b10 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24b20 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
24b30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24b40 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
24b50 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
24b60 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
24b70 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
24b80 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
24b90 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
24ba0 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
24bb0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
24bc0 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
24bd0 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
24be0 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
24bf0 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
24c00 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
24c10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24c20 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
24c30 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
24c40 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
24c50 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
24c60 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
24c70 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
24c80 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
24c90 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24ca0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
24cb0 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
24cc0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
24cd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24ce0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
24cf0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
24d00 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
24d10 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
24d20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
24d30 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
24d40 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
24d50 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
24d60 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
24d70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24d80 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
24d90 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
24da0 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
24db0 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
24dc0 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
24dd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24de0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
24df0 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
24e00 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
24e10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
24e20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24e30 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
24e40 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
24e50 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
24e60 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
24e70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24e80 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
24e90 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
24ea0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
24eb0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
24ec0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
24ed0 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
24ee0 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
24ef0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
24f00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24f10 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
24f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
24f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24f40 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
24f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
24f60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24f70 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
24f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24f90 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
24fa0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
24fb0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
24fc0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
24fd0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
24fe0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
24ff0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
25000 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
25010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25020 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
25030 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
25040 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
25050 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
25060 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
25070 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
25080 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
25090 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
250a0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
250b0 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
250c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
250d0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
250e0 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
250f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
25100 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
25110 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a         10../*.**
25120 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
25130 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
25140 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
25150 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
25160 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
25170 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
25180 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
25190 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
251a0 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
251b0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
251c0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
251d0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
251e0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
251f0 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
25200 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
25210 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
25220 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
25230 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
25240 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
25250 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
25260 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
25270 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
25280 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
25290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
252a0 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
252b0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
252c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
252d0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
252e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
252f0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
25300 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
25310 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
25320 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
25330 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
25340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
25350 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
25360 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
25370 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25380 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
25390 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
253a0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
253b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
253c0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
253d0 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
253e0 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
253f0 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
25400 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
25410 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
25420 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
25430 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
25440 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
25450 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
25460 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e  rom zSql.  ^When
25470 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
25480 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
25490 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
254a0 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
254b0 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
254c0 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
254d0 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
254e0 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
254f0 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
25500 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
25510 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
25520 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
25530 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
25540 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
25550 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
25560 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
25570 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
25580 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
25590 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
255a0 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
255b0 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
255c0 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
255d0 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
255e0 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
255f0 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
25600 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73   bytes as this s
25610 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d  aves SQLite from
25620 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61   having to.** ma
25630 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ke a copy of the
25640 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a   input string..*
25650 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
25660 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
25670 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
25680 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
25690 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
256a0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
256b0 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
256c0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
256d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
256e0 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
256f0 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
25700 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
25710 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
25720 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
25730 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
25740 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
25750 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
25760 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
25770 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
25780 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
25790 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
257a0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
257b0 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
257c0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
257d0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
257e0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
257f0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
25800 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
25810 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
25820 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
25830 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
25840 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
25850 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
25860 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
25870 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
25880 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
25890 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
258a0 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
258b0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
258c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
258d0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
258e0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
258f0 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
25900 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
25910 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
25920 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25930 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
25940 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
25950 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
25960 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
25970 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
25980 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
25990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
259a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
259b0 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
259c0 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
259d0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
259e0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
259f0 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
25a00 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
25a10 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
25a20 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
25a30 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
25a40 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
25a50 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
25a60 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
25a70 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
25a80 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
25a90 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
25aa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
25ab0 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
25ac0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
25ad0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
25ae0 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
25af0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
25b00 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
25b10 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
25b20 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
25b30 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
25b40 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
25b50 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
25b60 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
25b70 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
25b80 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
25b90 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
25ba0 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
25bb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25bc0 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
25bd0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
25be0 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
25bf0 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
25c00 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d  n it again. As m
25c10 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d  any as [SQLITE_M
25c20 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d  AX_SCHEMA_RETRY]
25c30 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c  .** retries will
25c40 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71   occur before sq
25c50 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76  lite3_step() giv
25c60 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e  es up and return
25c70 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c  s an error..** <
25c80 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
25c90 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
25ca0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
25cb0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
25cc0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
25cd0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
25ce0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
25cf0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
25d00 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
25d10 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
25d20 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
25d30 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
25d40 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
25d50 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
25d60 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
25d70 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
25d80 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
25d90 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
25da0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
25db0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
25dc0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
25dd0 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
25de0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
25df0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
25e00 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
25e10 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
25e20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
25e30 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
25e40 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
25e50 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
25e60 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
25e70 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
25e80 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
25e90 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
25ea0 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
25eb0 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
25ec0 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
25ed0 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
25ee0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
25ef0 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
25f00 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
25f10 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
25f20 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
25f30 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
25f40 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
25f50 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
25f60 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
25f70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25f80 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
25f90 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
25fa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
25fb0 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
25fc0 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
25fd0 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
25fe0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
25ff0 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
26000 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
26010 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
26020 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
26030 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
26040 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
26050 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
26060 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
26070 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
26080 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
26090 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
260a0 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
260b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
260c0 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
260d0 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT3] compile-
260e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
260f0 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a  nabled..** the .
26100 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
26110 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
26120 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
26130 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
26140 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26150 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26160 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26170 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
26180 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26190 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
261a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
261b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
261c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
261d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
261e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
261f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
26200 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
26210 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26220 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
26230 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
26240 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
26250 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
26260 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
26270 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
26280 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
26290 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
262a0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
262b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
262c0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
262d0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
262e0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
262f0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
26300 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
26310 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
26320 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
26330 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
26340 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
26350 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
26360 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26370 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
26380 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
26390 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
263a0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
263b0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
263c0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
263d0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
263e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
263f0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
26400 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
26410 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
26420 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
26430 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
26440 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26460 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26470 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
26480 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26490 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
264a0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
264b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
264c0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
264d0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
264e0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
264f0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
26500 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
26510 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
26520 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
26530 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
26540 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
26550 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26560 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
26570 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
26580 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
26590 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
265a0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
265b0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
265c0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
265d0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
265e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
265f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
26600 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
26610 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
26620 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
26630 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
26640 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
26650 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
26660 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
26670 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
26680 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  QL.**.** ^This i
26690 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
266a0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
266b0 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
266c0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
266d0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
266e0 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
266f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26700 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
26710 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
26720 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
26730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26740 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
26750 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26760 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
26770 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
26780 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
26790 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
267a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
267b0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
267c0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
267d0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
267e0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
267f0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26800 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
26810 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
26820 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
26830 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
26840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26850 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
26860 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
26870 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
26880 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
26890 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
268a0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
268b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
268c0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
268d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
268e0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
268f0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
26900 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
26910 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
26920 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
26930 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
26940 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
26950 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
26960 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
26970 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
26980 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
26990 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
269a0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
269b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
269c0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
269d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
269e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
269f0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
26a00 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
26a10 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
26a20 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
26a30 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
26a40 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
26a50 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
26a60 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
26a70 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
26a80 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
26a90 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
26aa0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
26ab0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
26ac0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
26ad0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
26ae0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
26af0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
26b00 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
26b10 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
26b20 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
26b30 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
26b40 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
26b50 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
26b60 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
26b70 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
26b80 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
26b90 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
26ba0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
26bb0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
26bc0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
26bd0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
26be0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
26bf0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
26c00 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
26c10 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
26c20 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
26c30 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
26c40 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
26c50 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
26c60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
26c70 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
26c80 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
26c90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26ca0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
26cb0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
26cc0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
26cd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26ce0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
26cf0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26d00 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26d10 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
26d20 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
26d30 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
26d40 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
26d50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
26d60 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
26d70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26d80 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
26d90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
26da0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
26db0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
26dc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
26dd0 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
26de0 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
26df0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
26e00 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
26e10 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
26e20 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
26e30 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
26e40 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
26e50 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
26e60 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
26e70 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
26e80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26e90 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
26ea0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
26eb0 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
26ec0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
26ed0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
26ee0 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
26ef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26f00 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
26f10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
26f20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
26f30 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
26f40 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
26f50 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
26f60 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
26f70 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
26f80 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
26f90 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
26fa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26fb0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
26fc0 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
26fd0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
26fe0 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
26ff0 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
27000 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
27010 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
27020 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
27030 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
27040 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
27050 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
27060 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
27070 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
27080 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
27090 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
270a0 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
270b0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
270c0 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
270d0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
270e0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
270f0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
27100 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
27110 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
27120 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
27130 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
27140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27150 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
27160 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
27170 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
27180 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
27190 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
271a0 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
271b0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
271c0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
271d0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
271e0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
271f0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
27200 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
27210 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
27220 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
27230 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
27240 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
27250 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
27260 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
27270 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
27280 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
27290 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
272a0 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
272b0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
272c0 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
272d0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
272e0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
272f0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
27300 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27310 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
27320 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
27330 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
27340 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
27350 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
27360 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
27370 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
27380 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
27390 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
273a0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
273b0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
273c0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
273d0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
273e0 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
273f0 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
27400 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
27410 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
27420 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
27430 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
27440 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
27450 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
27460 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
27470 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
27480 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
27490 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
274a0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
274b0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
274c0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
274d0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
274e0 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
274f0 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
27500 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
27510 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
27520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
27530 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
27540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
27550 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
27560 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
27570 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
27580 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
27590 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
275a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
275b0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
275c0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
275d0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
275e0 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
275f0 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
27600 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
27610 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
27620 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
27630 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
27640 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
27650 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
27660 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
27670 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
27680 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
27690 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
276a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
276b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
276c0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
276d0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
276e0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
276f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
27700 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27710 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
27720 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
27730 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
27740 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
27750 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
27760 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
27770 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
27780 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
27790 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
277a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
277b0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
277c0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
277d0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
277e0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
277f0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
27800 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27810 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
27820 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
27830 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
27840 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
27850 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27860 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
27870 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
27880 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
27890 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
278a0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
278b0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
278c0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
278d0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
278e0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
278f0 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
27900 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
27910 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
27920 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
27930 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
27940 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
27950 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
27960 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
27970 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
27980 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
27990 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
279a0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
279b0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
279c0 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
279d0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
279e0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
279f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
27a00 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
27a10 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
27a20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
27a30 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
27a40 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
27a50 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
27a60 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
27a70 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
27a80 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
27a90 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
27aa0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
27ab0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
27ac0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
27ad0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
27ae0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
27af0 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
27b00 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
27b10 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
27b20 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
27b30 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
27b40 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
27b50 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
27b60 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
27b70 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
27b80 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
27b90 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
27ba0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
27bb0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
27bc0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
27bd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27be0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
27bf0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
27c00 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
27c10 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
27c20 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
27c30 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
27c40 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
27c50 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
27c60 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
27c70 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
27c80 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
27c90 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
27ca0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
27cb0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
27cc0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
27cd0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
27ce0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
27cf0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
27d00 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
27d10 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
27d20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
27d30 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
27d40 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
27d50 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
27d60 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
27d70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
27d80 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
27d90 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
27da0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
27db0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
27dc0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
27dd0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
27de0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
27df0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
27e00 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
27e10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
27e20 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
27e30 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
27e40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27e50 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
27e60 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
27e70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
27e80 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
27e90 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
27ea0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
27eb0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
27ec0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
27ed0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
27ee0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
27ef0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
27f00 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
27f10 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
27f20 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
27f30 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
27f40 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
27f50 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
27f60 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
27f70 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
27f80 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
27f90 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
27fa0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
27fb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27fc0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
27fd0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
27fe0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
27ff0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
28000 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
28010 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
28020 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
28030 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
28040 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
28050 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
28060 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
28070 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
28080 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
28090 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
280a0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
280b0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
280c0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
280d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
280e0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
280f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
28100 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
28110 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28120 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
28130 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
28140 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
28150 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
28160 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
28170 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
28180 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
28190 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
281a0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
281b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
281c0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
281d0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
281e0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
281f0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
28200 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
28210 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
28220 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
28230 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
28240 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
28250 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
28260 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
28270 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
28280 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
28290 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
282a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
282b0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
282c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
282d0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
282e0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
282f0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
28300 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
28310 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
28320 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
28330 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
28340 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
28350 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
28360 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
28370 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
28380 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
28390 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
283a0 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
283b0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
283c0 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
283d0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
283e0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
283f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28400 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61  ) then that para
28410 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
28420 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
28430 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
28440 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
28450 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
28460 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
28470 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
28480 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
28490 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
284a0 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
284b0 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
284c0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
284d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
284e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
284f0 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
28500 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
28510 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
28520 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
28530 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
28540 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
28550 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
28560 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
28570 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
28580 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
28590 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
285a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
285b0 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
285c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
285d0 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
285e0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
285f0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
28600 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
28610 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
28620 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
28630 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
28640 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
28650 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
28660 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
28670 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
28680 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
28690 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  lob(),.** sqlite
286a0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f  3_bind_text(), o
286b0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
286c0 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20  ext16() fails.  
286d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
286e0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
286f0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
28700 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
28710 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
28720 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
28730 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
28740 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
28750 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
28760 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
28770 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
28780 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
28790 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
287a0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
287b0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
287c0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
287d0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
287e0 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
287f0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
28800 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
28810 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
28820 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
28830 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
28840 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
28850 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
28860 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
28870 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
28880 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
28890 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
288a0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
288b0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
288c0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
288d0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
288e0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
288f0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
28900 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
28910 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
28920 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
28930 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
28940 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
28950 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
28960 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
28970 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
28980 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
28990 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
289a0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
289b0 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
289c0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
289d0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
289e0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
289f0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
28a00 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
28a10 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
28a20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
28a30 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
28a40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
28a50 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
28a60 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
28a70 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
28a80 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
28a90 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
28aa0 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
28ab0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
28ac0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
28ad0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
28ae0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
28af0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
28b00 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
28b10 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
28b20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28b30 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
28b40 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
28b50 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
28b60 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
28b70 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
28b80 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
28b90 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
28ba0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28bb0 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
28bc0 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
28bd0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
28be0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
28bf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
28c00 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
28c10 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
28c20 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
28c30 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
28c40 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
28c50 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
28c60 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
28c70 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
28c80 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
28c90 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
28ca0 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
28cb0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
28cc0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
28cd0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
28ce0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
28cf0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
28d00 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
28d10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28d20 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
28d30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28d40 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
28d50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
28d60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28d70 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
28d80 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
28d90 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
28da0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
28db0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28dc0 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
28dd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28de0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  int, double);.SQ
28df0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28e00 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
28e10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28e20 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
28e30 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
28e40 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
28e50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
28e60 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51  lite3_int64);.SQ
28e70 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28e80 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
28e90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28ea0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
28eb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28ec0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
28ed0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
28ee0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
28ef0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
28f00 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28f10 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28f20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28f30 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
28f40 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
28f50 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
28f60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
28f70 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
28f80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
28f90 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
28fa0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
28fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28fc0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
28fd0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
28fe0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
28ff0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
29000 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
29010 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
29020 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
29030 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
29040 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
29050 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
29060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29070 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
29080 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
29090 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
290a0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
290b0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
290c0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
290d0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
290e0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
290f0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
29100 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
29110 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
29120 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
29130 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
29140 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
29150 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
29160 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
29170 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
29180 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
29190 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
291a0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
291b0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
291c0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
291d0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
291e0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
291f0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
29200 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
29210 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
29220 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
29230 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
29240 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29250 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
29260 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
29270 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29280 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
29290 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
292a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
292b0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
292c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
292d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
292e0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
292f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
29300 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
29310 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
29320 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
29330 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29340 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
29350 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
29360 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
29370 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
29380 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
29390 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
293a0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
293b0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
293c0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
293d0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
293e0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
293f0 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
29400 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
29410 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
29420 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
29430 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
29440 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
29450 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
29460 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
29470 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
29480 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
29490 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
294a0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
294b0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
294c0 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
294d0 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
294e0 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
294f0 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
29500 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
29510 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
29520 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
29530 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
29540 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
29550 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
29560 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
29570 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
29580 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
29590 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
295a0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
295b0 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
295c0 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
295d0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
295e0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
295f0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
29600 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
29610 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
29620 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
29630 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
29640 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
29650 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
29660 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29670 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
29680 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29690 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
296a0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
296b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
296c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
296d0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
296e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
296f0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
29700 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
29710 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
29720 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
29730 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
29740 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
29750 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
29760 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
29770 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
29780 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
29790 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
297a0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
297b0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
297c0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
297d0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
297e0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
297f0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
29800 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
29810 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
29820 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
29830 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
29840 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
29850 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
29860 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
29870 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
29880 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
29890 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
298a0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
298b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
298c0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
298d0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
298e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
298f0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
29900 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29910 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
29920 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
29930 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29940 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
29950 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
29960 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29970 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
29980 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29990 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
299a0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
299b0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
299c0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
299d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
299e0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
299f0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
29a00 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
29a10 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
29a20 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
29a30 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
29a40 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
29a50 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
29a60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
29a70 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
29a80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29a90 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
29aa0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
29ab0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
29ac0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
29ad0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
29ae0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
29af0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
29b00 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
29b10 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
29b20 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
29b30 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
29b40 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
29b50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
29b60 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
29b70 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
29b80 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29b90 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
29ba0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
29bb0 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
29bc0 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
29bd0 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
29be0 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
29bf0 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
29c00 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
29c10 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29c20 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
29c30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29c40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
29c50 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
29c60 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
29c70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
29c80 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
29c90 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
29ca0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
29cb0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
29cc0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
29cd0 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
29ce0 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
29cf0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
29d00 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
29d10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
29d20 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
29d30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29d40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
29d50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
29d60 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
29d70 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
29d80 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
29d90 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
29da0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
29db0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
29dc0 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
29dd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
29de0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29df0 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
29e00 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
29e10 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
29e20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
29e30 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
29e40 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
29e50 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
29e60 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
29e70 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
29e80 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
29e90 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
29ea0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
29eb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29ec0 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
29ed0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
29ee0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
29ef0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
29f00 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
29f10 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
29f20 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
29f30 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29f40 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
29f50 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
29f60 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
29f70 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
29f80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
29f90 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
29fa0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
29fb0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
29fc0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
29fd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
29fe0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
29ff0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2a000 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2a010 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2a020 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2a030 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2a040 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2a050 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2a060 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2a070 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2a080 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2a090 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2a0a0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2a0b0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2a0c0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2a0d0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2a0e0 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2a0f0 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2a100 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2a110 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2a120 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2a130 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2a140 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2a150 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2a160 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2a170 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2a180 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2a190 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2a1a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2a1b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2a1c0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
2a1d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a1e0 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2a1f0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2a200 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2a210 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
2a220 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2a230 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2a240 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2a250 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2a260 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2a270 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2a280 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2a290 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2a2a0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2a2b0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2a2c0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2a2d0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2a2e0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2a2f0 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2a300 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2a310 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2a320 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2a330 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2a340 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2a350 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2a360 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2a370 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2a380 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2a390 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2a3a0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2a3b0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2a3c0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2a3d0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2a3e0 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2a3f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2a400 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2a410 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2a420 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2a430 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2a440 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2a450 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2a460 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2a470 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2a480 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2a490 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2a4a0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2a4b0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2a4c0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2a4d0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2a4e0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2a4f0 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2a500 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2a510 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2a520 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2a530 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2a540 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2a550 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2a560 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2a570 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2a580 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a590 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2a5a0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2a5b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2a5c0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2a5d0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2a5e0 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2a5f0 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2a600 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2a610 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2a620 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2a630 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2a640 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2a650 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2a660 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2a670 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2a680 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2a690 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2a6a0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2a6b0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2a6c0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2a6d0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2a6e0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2a6f0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2a700 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2a710 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2a720 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2a730 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2a740 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2a750 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2a760 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2a770 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2a780 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2a790 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2a7a0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2a7b0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2a7c0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2a7d0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2a7e0 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2a7f0 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2a800 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2a810 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2a820 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2a830 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2a840 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2a850 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2a860 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2a870 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2a880 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2a890 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2a8a0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2a8b0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2a8c0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2a8d0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2a8e0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2a8f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2a900 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2a910 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
2a920 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2a930 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
2a940 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2a950 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2a960 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
2a970 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
2a980 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2a990 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2a9a0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
2a9b0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2a9c0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
2a9d0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
2a9e0 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
2a9f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2aa00 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
2aa10 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
2aa20 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2aa30 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2aa40 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2aa50 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2aa60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2aa70 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2aa80 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2aa90 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2aaa0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2aab0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2aac0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
2aad0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2aae0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2aaf0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2ab00 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2ab10 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2ab20 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2ab30 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2ab40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2ab50 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
2ab60 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2ab70 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2ab80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2ab90 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
2aba0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2abb0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2abc0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2abd0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2abe0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2abf0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2ac00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
2ac10 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
2ac20 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
2ac30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2ac40 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2ac50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2ac60 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2ac70 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2ac80 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2ac90 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2aca0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2acb0 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2acc0 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2acd0 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2ace0 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2acf0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2ad00 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2ad10 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2ad20 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
2ad30 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
2ad40 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
2ad50 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2ad60 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
2ad70 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
2ad80 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
2ad90 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
2ada0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2adb0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2adc0 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
2add0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
2ade0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2adf0 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
2ae00 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2ae10 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
2ae20 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
2ae30 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
2ae40 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
2ae50 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2ae60 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
2ae70 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
2ae80 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
2ae90 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
2aea0 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
2aeb0 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
2aec0 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
2aed0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2aee0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2aef0 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2af00 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2af10 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2af20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2af30 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2af40 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2af50 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2af60 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2af70 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2af80 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2af90 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2afa0 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2afb0 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2afc0 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2afd0 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2afe0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2aff0 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2b000 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2b010 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2b020 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2b030 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2b040 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2b050 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2b060 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2b070 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2b080 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49   values..*/.SQLI
2b090 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2b0a0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2b0b0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2b0c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2b0d0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2b0e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2b0f0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2b100 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b110 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b120 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2b130 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2b140 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2b150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b160 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2b170 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2b180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b190 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2b1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b1b0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2b1c0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2b1d0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2b1e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2b1f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b200 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2b210 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2b220 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2b230 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2b240 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2b250 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2b260 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2b270 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2b280 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2b290 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2b2a0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2b2b0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2b2c0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2b2d0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2b2e0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2b2f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b300 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2b310 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2b320 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2b330 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2b340 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2b350 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2b360 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2b370 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2b380 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2b390 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2b3a0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2b3b0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2b3c0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2b3d0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2b3e0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2b3f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2b400 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2b410 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2b420 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2b430 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2b440 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2b450 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2b460 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2b470 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2b480 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2b490 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2b4a0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2b4b0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2b4c0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2b4d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2b4e0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2b4f0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2b500 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2b510 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2b520 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2b530 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2b540 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2b550 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2b560 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2b570 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2b580 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2b590 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2b5a0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2b5b0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2b5c0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2b5d0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2b5e0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2b5f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2b600 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2b610 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2b620 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2b630 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2b640 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2b650 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2b660 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2b670 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2b680 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2b690 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2b6a0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2b6b0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2b6c0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2b6d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2b6e0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2b6f0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2b700 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2b710 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2b720 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2b730 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2b740 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2b750 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2b760 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2b770 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2b780 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2b790 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2b7a0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2b7b0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2b7c0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2b7d0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2b7e0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2b7f0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2b800 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2b810 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2b820 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2b830 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2b840 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2b850 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2b860 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2b870 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2b880 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2b890 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2b8a0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2b8b0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2b8c0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2b8d0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2b8e0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2b8f0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2b900 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2b910 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2b920 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2b930 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2b940 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2b950 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2b960 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2b970 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2b980 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2b990 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2b9a0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2b9b0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2b9c0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2b9d0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2b9e0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2b9f0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2ba00 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2ba10 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2ba20 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2ba30 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2ba40 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2ba50 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2ba60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2ba70 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2ba80 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2ba90 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2baa0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2bab0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2bac0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2bad0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2bae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2baf0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2bb00 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2bb10 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2bb20 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2bb30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2bb40 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2bb50 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2bb60 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2bb70 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2bb80 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2bb90 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2bba0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2bbb0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2bbc0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2bbd0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2bbe0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2bbf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2bc00 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2bc10 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2bc20 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2bc30 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2bc40 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2bc50 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2bc60 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2bc70 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2bc80 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2bc90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2bca0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2bcb0 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2bcc0 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2bcd0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2bce0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2bcf0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2bd00 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2bd10 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2bd20 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2bd30 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2bd40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2bd50 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2bd60 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2bd70 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2bd80 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2bd90 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2bda0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2bdb0 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2bdc0 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2bdd0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2bde0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2bdf0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2be00 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2be10 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2be20 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2be30 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2be40 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2be50 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2be60 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2be70 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2be80 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2be90 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2bea0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2beb0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2bec0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2bed0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2bee0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2bef0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2bf00 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2bf10 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2bf20 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2bf30 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2bf40 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2bf50 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2bf60 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2bf70 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2bf80 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2bf90 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2bfa0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2bfb0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2bfc0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2bfd0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2bfe0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2bff0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2c000 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2c010 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2c020 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2c030 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c040 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2c050 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2c060 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2c070 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2c080 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2c090 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2c0a0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2c0b0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2c0c0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2c0d0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2c0e0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2c0f0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2c100 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2c110 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2c120 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2c130 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2c140 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2c150 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2c160 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2c170 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2c180 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2c190 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2c1a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2c1b0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2c1c0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2c1d0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2c1e0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2c1f0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2c200 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2c210 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2c220 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2c230 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2c240 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2c250 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
2c260 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2c270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c280 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
2c290 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
2c2a0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
2c2b0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2c2c0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2c2d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2c2e0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2c2f0 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
2c300 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2c310 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
2c320 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2c330 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
2c340 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
2c350 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
2c360 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
2c370 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
2c380 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
2c390 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
2c3a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
2c3b0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2c3c0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
2c3d0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
2c3e0 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
2c3f0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2c400 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
2c410 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
2c420 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
2c430 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
2c440 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c450 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
2c460 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
2c470 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
2c480 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2c490 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
2c4a0 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
2c4b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2c4c0 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
2c4d0 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
2c4e0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2c4f0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
2c500 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
2c510 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
2c520 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
2c530 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
2c540 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
2c550 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
2c560 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
2c570 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
2c580 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
2c590 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
2c5a0 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
2c5b0 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
2c5c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2c5d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2c5e0 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
2c5f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
2c600 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2c610 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2c620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c630 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2c640 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
2c650 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2c660 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
2c670 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
2c680 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
2c690 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
2c6a0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
2c6b0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
2c6c0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2c6d0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
2c6e0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
2c6f0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
2c700 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
2c710 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
2c720 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
2c730 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2c740 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2c750 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2c760 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2c770 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2c780 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2c790 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2c7a0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2c7b0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2c7c0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2c7d0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2c7e0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2c7f0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2c800 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2c810 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2c820 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2c830 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2c840 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2c850 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2c860 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2c870 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2c880 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2c890 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2c8a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2c8b0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2c8c0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2c8d0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2c8e0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2c8f0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2c900 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2c910 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2c920 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2c930 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2c940 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
2c950 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2c960 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2c970 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2c980 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2c990 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2c9a0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
2c9b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c9c0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2c9d0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2c9e0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2c9f0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2ca00 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2ca10 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2ca20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2ca30 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2ca40 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2ca50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ca60 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2ca70 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2ca80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2ca90 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2caa0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2cab0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2cac0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2cad0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2cae0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2caf0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2cb00 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2cb10 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2cb20 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2cb30 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2cb40 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2cb50 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2cb60 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2cb70 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2cb80 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2cb90 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2cba0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2cbb0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2cbc0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2cbd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2cbe0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2cbf0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2cc00 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2cc10 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2cc20 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2cc30 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2cc40 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2cc50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2cc60 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2cc70 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2cc80 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2cc90 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2cca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ccb0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2ccc0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2ccd0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2cce0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2ccf0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2cd00 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2cd10 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2cd20 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2cd30 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2cd40 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2cd50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2cd60 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2cd70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2cd80 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2cd90 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2cda0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2cdb0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2cdc0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2cdd0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2cde0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2cdf0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2ce00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ce10 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2ce20 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2ce30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2ce40 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2ce50 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2ce60 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2ce70 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2ce80 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2ce90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2cea0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2ceb0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2cec0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2ced0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2cee0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2cef0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2cf00 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2cf10 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2cf20 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2cf30 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2cf40 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2cf50 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2cf60 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2cf70 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2cf80 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2cf90 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2cfa0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2cfb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2cfc0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2cfd0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2cfe0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2cff0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2d000 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2d010 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2d020 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2d030 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2d040 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2d050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2d060 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2d070 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2d080 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2d090 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2d0a0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2d0b0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2d0c0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2d0d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2d0e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2d0f0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2d100 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2d110 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2d120 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2d130 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2d140 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2d150 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2d160 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2d170 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2d180 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2d190 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2d1a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2d1b0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2d1c0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2d1d0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2d1e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d1f0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2d200 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2d210 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2d220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d230 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2d240 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2d250 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2d260 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2d270 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2d280 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2d290 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2d2a0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2d2b0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d2c0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2d2d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d2e0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2d2f0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2d300 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2d310 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2d320 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2d330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d340 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2d350 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2d360 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d370 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2d380 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2d390 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2d3a0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2d3b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d3c0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2d3d0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2d3e0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2d3f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2d400 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2d410 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d420 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2d430 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2d440 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d450 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2d460 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2d470 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2d480 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2d490 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2d4a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2d4b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2d4c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2d4d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d4e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2d4f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d500 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
2d510 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
2d520 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2d530 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d540 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
2d550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d560 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
2d570 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
2d580 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
2d590 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2d5a0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
2d5b0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2d5c0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2d5d0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2d5e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2d5f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
2d600 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
2d610 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
2d620 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2d630 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2d640 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2d650 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
2d660 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2d670 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d680 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
2d690 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d6a0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
2d6b0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
2d6c0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
2d6d0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
2d6e0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2d6f0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2d700 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2d710 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2d720 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2d730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
2d740 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
2d750 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d760 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
2d770 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2d780 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d790 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
2d7a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d7b0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
2d7c0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2d7d0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
2d7e0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2d7f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2d800 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2d810 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2d820 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d830 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2d840 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2d850 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2d860 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2d870 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2d880 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2d890 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2d8a0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2d8b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2d8c0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2d8d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d8e0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
2d8f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2d900 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2d910 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2d920 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2d930 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2d940 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2d950 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2d960 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2d970 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2d980 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2d990 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2d9a0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2d9b0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2d9c0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2d9d0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2d9e0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2d9f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2da00 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2da10 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2da20 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2da30 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2da40 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2da50 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2da60 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2da70 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2da80 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2da90 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2daa0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2dab0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2dac0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2dad0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2dae0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2daf0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2db00 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2db10 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2db20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2db30 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2db40 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2db50 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2db60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2db70 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2db80 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2db90 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2dba0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2dbb0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2dbc0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2dbd0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2dbe0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2dbf0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2dc00 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2dc10 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2dc20 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2dc30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2dc40 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2dc50 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2dc60 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2dc70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2dc80 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2dc90 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2dca0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
2dcb0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2dcc0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2dcd0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2dce0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2dcf0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2dd00 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2dd10 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2dd20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
2dd30 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
2dd40 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2dd50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2dd60 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
2dd70 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2dd80 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2dd90 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
2dda0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2ddb0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2ddc0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2ddd0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2dde0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2ddf0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
2de00 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2de10 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
2de20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2de30 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2de40 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2de50 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2de60 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
2de70 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2de80 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2de90 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
2dea0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
2deb0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2dec0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
2ded0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
2dee0 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
2def0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
2df00 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
2df10 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
2df20 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
2df30 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
2df40 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
2df50 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
2df60 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
2df70 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
2df80 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
2df90 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
2dfa0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
2dfb0 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
2dfc0 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
2dfd0 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
2dfe0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
2dff0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
2e000 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2e010 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
2e020 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
2e030 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2e040 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
2e050 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2e060 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
2e070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e080 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
2e090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e0a0 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
2e0b0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
2e0c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
2e0d0 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
2e0e0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
2e0f0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
2e100 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
2e110 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2e120 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2e130 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
2e140 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2e150 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
2e160 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2e170 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2e180 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
2e190 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
2e1a0 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
2e1b0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
2e1c0 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
2e1d0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2e1e0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2e1f0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
2e200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e210 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
2e220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e230 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2e240 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2e250 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2e260 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2e270 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
2e280 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2e290 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
2e2a0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2e2b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2e2c0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2e2d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2e2e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2e2f0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2e300 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2e310 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
2e320 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2e330 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
2e340 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
2e350 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
2e360 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
2e370 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
2e380 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
2e390 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
2e3a0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
2e3b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2e3c0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
2e3d0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
2e3e0 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
2e3f0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
2e400 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
2e410 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
2e420 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
2e430 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
2e440 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
2e450 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
2e460 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
2e470 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
2e480 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
2e490 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
2e4a0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
2e4b0 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
2e4c0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
2e4d0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
2e4e0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
2e4f0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
2e500 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
2e510 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
2e520 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2e530 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
2e540 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2e550 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2e560 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2e570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2e580 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2e590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e5a0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2e5b0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2e5c0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
2e5d0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2e5e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
2e5f0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
2e600 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2e610 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
2e620 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
2e630 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
2e640 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e650 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
2e660 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2e670 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
2e680 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
2e690 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
2e6a0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
2e6b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2e6c0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
2e6d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e6e0 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
2e6f0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
2e700 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
2e710 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
2e720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e730 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2e740 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
2e750 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
2e760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e770 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
2e780 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
2e790 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2e7a0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
2e7b0 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
2e7c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e7d0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
2e7e0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2e7f0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
2e800 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2e810 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
2e820 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
2e830 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
2e840 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2e850 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2e860 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2e870 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
2e880 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
2e890 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
2e8a0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
2e8b0 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
2e8c0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
2e8d0 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
2e8e0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
2e8f0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
2e900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e910 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2e920 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2e930 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2e940 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2e950 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2e960 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2e970 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2e980 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2e990 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2e9a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2e9b0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2e9c0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2e9d0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2e9e0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2e9f0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2ea00 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2ea10 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2ea20 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2ea30 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2ea40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2ea50 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2ea60 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2ea70 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
2ea80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2ea90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2eaa0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2eab0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2eac0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2ead0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eae0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2eaf0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2eb00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2eb10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2eb20 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
2eb30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2eb40 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
2eb50 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2eb60 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2eb70 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2eb80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2eb90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eba0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2ebb0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2ebc0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2ebd0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
2ebe0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
2ebf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2ec00 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2ec10 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
2ec20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2ec30 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2ec40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2ec50 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
2ec60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2ec70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2ec80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ec90 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2eca0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ecb0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
2ecc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ecd0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2ece0 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  PI sqlite3_value
2ecf0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ed00 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2ed10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2ed20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ed30 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2ed40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2ed50 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2ed60 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2ed70 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2ed80 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2ed90 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2eda0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2edb0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2edc0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2edd0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2ede0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2edf0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2ee00 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2ee10 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2ee20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2ee30 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2ee40 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2ee50 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2ee60 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2ee70 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2ee80 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2ee90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2eea0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2eeb0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2eec0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2eed0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2eee0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2eef0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ef00 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2ef10 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2ef20 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2ef30 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2ef40 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2ef50 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2ef60 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2ef70 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2ef80 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2ef90 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2efa0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2efb0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2efc0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2efd0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2efe0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2eff0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2f000 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2f010 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2f020 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2f030 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2f040 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2f050 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2f060 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2f070 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2f080 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2f090 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2f0a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2f0b0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2f0c0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2f0d0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2f0e0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2f0f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2f100 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2f110 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2f120 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2f130 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2f140 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2f150 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2f160 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2f170 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2f180 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2f190 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2f1a0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2f1b0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2f1c0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2f1d0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2f1e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f1f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f200 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2f210 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2f220 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2f230 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2f240 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2f250 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2f260 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2f270 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2f280 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f290 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2f2a0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2f2b0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2f2c0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2f2d0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
2f2e0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2f2f0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2f300 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2f310 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2f320 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f330 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2f340 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2f350 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2f360 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2f370 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2f380 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2f390 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
2f3a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2f3b0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2f3c0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2f3d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f3e0 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
2f3f0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2f400 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2f410 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2f420 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2f430 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2f440 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2f450 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2f460 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2f470 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2f480 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
2f490 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2f4a0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
2f4b0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
2f4c0 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
2f4d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2f4e0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2f4f0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
2f500 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2f510 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2f520 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2f530 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2f540 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2f550 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2f560 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
2f570 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2f580 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2f590 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2f5a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2f5b0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2f5c0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
2f5d0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
2f5e0 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
2f5f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f600 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2f610 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f620 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c  ement] S..*/.SQL
2f630 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2f640 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2f650 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2f660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f670 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2f680 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2f690 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2f6a0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2f6b0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
2f6c0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2f6d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2f6e0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
2f6f0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2f700 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2f710 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
2f720 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2f730 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
2f740 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
2f750 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2f760 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
2f770 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
2f780 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2f790 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
2f7a0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
2f7b0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
2f7c0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
2f7d0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
2f7e0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
2f7f0 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
2f800 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2f810 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
2f820 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
2f830 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
2f840 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2f850 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
2f860 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
2f870 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
2f880 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
2f890 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
2f8a0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
2f8b0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2f8c0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2f8d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2f8e0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2f8f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f900 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2f910 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2f920 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2f930 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
2f940 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
2f950 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
2f960 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2f970 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
2f980 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2f990 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
2f9a0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
2f9b0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
2f9c0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
2f9d0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2f9e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2f9f0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2fa00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2fa10 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
2fa20 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
2fa30 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
2fa40 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
2fa50 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
2fa60 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
2fa70 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
2fa80 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2fa90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
2faa0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
2fab0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
2fac0 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
2fad0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
2fae0 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
2faf0 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
2fb00 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2fb10 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2fb20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2fb30 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2fb40 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
2fb50 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
2fb60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2fb70 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2fb80 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
2fb90 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2fba0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
2fbb0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2fbc0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
2fbd0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
2fbe0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
2fbf0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2fc00 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2fc10 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
2fc20 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2fc30 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
2fc40 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
2fc50 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
2fc60 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2fc70 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2fc80 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
2fc90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
2fca0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
2fcb0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
2fcc0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
2fcd0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
2fce0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2fcf0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2fd00 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
2fd10 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
2fd20 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
2fd30 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
2fd40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
2fd50 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
2fd60 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76   parameters.  Ev
2fd70 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ery SQL function
2fd80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fd90 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20  must be able to 
2fda0 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46  work.** with UTF
2fdb0 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
2fdc0 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
2fdd0 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
2fde0 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
2fdf0 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
2fe00 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
2fe10 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
2fe20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
2fe30 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
2fe40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fe50 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
2fe60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fe70 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
2fe80 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
2fe90 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
2fea0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2feb0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
2fec0 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
2fed0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2fee0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2fef0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
2ff00 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
2ff10 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
2ff20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
2ff30 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
2ff40 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
2ff50 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
2ff60 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
2ff70 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
2ff80 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
2ff90 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
2ffa0 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
2ffb0 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
2ffc0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
2ffd0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
2ffe0 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
2fff0 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
30000 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
30010 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
30020 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
30030 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
30040 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
30050 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
30060 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
30070 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
30080 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
30090 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
300a0 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
300b0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
300c0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
300d0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
300e0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
300f0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
30100 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
30110 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
30120 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
30130 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
30140 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
30150 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
30160 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
30170 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
30180 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
30190 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
301a0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
301b0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
301c0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
301d0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
301e0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
301f0 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
30200 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
30210 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
30220 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
30230 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
30240 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
30250 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
30260 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
30270 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
30280 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
30290 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
302a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
302b0 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
302c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
302d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
302e0 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
302f0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
30300 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
30310 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
30320 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
30330 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
30340 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
30350 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
30360 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
30370 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
30380 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
30390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
303a0 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
303b0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
303c0 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
303d0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
303e0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
303f0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
30400 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
30410 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
30420 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
30430 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
30440 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
30450 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
30460 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
30470 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
30480 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
30490 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
304a0 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
304b0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
304c0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
304d0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
304e0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
304f0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
30500 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
30510 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
30520 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
30530 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
30540 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
30550 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
30560 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
30570 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
30580 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
30590 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
305a0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
305b0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
305c0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
305d0 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
305e0 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
305f0 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
30600 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
30610 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
30620 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
30630 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
30640 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
30650 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
30660 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
30670 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
30680 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
30690 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
306a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
306b0 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
306c0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
306d0 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
306e0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
306f0 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
30700 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
30710 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
30720 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
30730 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
30740 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
30750 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
30760 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
30770 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
30780 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
30790 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
307a0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
307b0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
307c0 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
307d0 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
307e0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
307f0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
30800 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
30810 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
30820 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30830 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
30840 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30850 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
30860 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
30870 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
30880 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
30890 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
308a0 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
308b0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
308c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
308d0 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
308e0 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
308f0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
30900 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
30910 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
30920 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
30930 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30940 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
30950 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
30960 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
30970 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
30980 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
30990 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
309a0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
309b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
309c0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
309d0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
309e0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
309f0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
30a00 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
30a10 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
30a20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
30a30 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
30a40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30a50 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
30a60 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
30a70 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
30a80 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
30a90 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
30aa0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
30ab0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
30ac0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30ad0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30ae0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30af0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
30b00 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30b10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30b20 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
30b30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30b40 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
30b50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
30b60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
30b70 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
30b80 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
30b90 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
30ba0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
30bb0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
30bc0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
30bd0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
30be0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
30bf0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
30c00 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
30c10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
30c20 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
30c30 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
30c40 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
30c50 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
30c60 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
30c70 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
30c80 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
30c90 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
30ca0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
30cb0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
30cc0 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
30cd0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
30ce0 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
30cf0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
30d00 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
30d10 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
30d20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
30d30 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
30d40 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
30d50 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
30d60 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
30d70 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
30d80 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
30d90 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
30da0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
30db0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
30dc0 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
30dd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30de0 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
30df0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
30e00 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
30e10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
30e20 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
30e30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30e40 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
30e50 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
30e60 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
30e70 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
30e80 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
30e90 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
30ea0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
30eb0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
30ec0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
30ed0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
30ee0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
30ef0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
30f00 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
30f10 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
30f20 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
30f30 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
30f40 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
30f50 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
30f60 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
30f70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
30f80 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
30f90 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
30fa0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
30fb0 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
30fc0 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
30fd0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
30fe0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
30ff0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31000 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
31010 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
31020 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
31030 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
31040 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
31050 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
31060 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
31070 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
31080 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
31090 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
310a0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
310b0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
310c0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
310d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
310e0 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
310f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
31100 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31110 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
31120 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
31130 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
31140 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31150 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
31160 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
31170 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
31180 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
31190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
311a0 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
311b0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
311c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
311d0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
311e0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
311f0 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
31200 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
31210 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
31220 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
31230 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
31240 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
31250 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
31260 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
31270 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
31280 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
31290 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
312a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
312b0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
312c0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
312d0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
312e0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
312f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
31300 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
31310 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
31320 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31330 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
31340 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
31350 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
31360 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
31370 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
31380 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
31390 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
313a0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
313b0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
313c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
313d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
313e0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
313f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31400 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
31410 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31420 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
31430 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31440 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
31450 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
31460 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
31470 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
31480 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
31490 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
314a0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
314b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
314c0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
314d0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
314e0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
314f0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
31500 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
31510 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
31520 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
31530 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
31540 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
31550 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
31560 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
31570 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
31580 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
31590 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
315a0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
315b0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
315c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
315d0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
315e0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
315f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
31600 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
31610 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
31620 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
31630 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31640 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
31650 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
31660 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
31670 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
31680 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
31690 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
316a0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
316b0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
316c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
316d0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
316e0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
316f0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
31700 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
31710 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
31720 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
31730 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
31740 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
31750 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
31760 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
31770 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
31780 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
31790 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
317a0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
317b0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
317c0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
317d0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
317e0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
317f0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
31800 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
31810 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
31820 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
31830 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
31840 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
31850 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
31860 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
31870 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
31880 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
31890 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
318a0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
318b0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
318c0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
318d0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
318e0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
318f0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
31900 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
31910 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
31920 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
31930 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
31940 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
31950 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
31960 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
31970 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31980 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31990 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
319a0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
319b0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
319c0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
319d0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
319e0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
319f0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
31a00 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
31a10 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
31a20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
31a30 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
31a40 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
31a50 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
31a60 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31a70 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
31a80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
31a90 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
31aa0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
31ab0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
31ac0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
31ad0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
31ae0 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
31af0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
31b00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
31b10 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
31b20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
31b30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31b40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
31b50 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
31b60 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
31b70 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
31b80 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
31b90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
31ba0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31bb0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
31bc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
31bd0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
31be0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
31bf0 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
31c00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
31c10 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
31c20 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
31c30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
31c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31c50 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31c60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31c70 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
31c80 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31c90 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
31ca0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
31cb0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
31cc0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
31cd0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
31ce0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
31cf0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
31d00 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
31d10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31d20 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
31d30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
31d40 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31d50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
31d60 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
31d70 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
31d80 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
31d90 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
31da0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
31db0 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
31dc0 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
31dd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
31de0 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
31df0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
31e00 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
31e10 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
31e20 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
31e30 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
31e40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31e50 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
31e60 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
31e70 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
31e80 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
31e90 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
31ea0 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
31eb0 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
31ec0 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
31ed0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
31ee0 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
31ef0 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
31f00 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
31f10 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
31f20 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31f30 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
31f40 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
31f50 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
31f60 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
31f70 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
31f80 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
31f90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
31fa0 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
31fb0 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
31fc0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
31fd0 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
31fe0 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
31ff0 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
32000 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
32010 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
32020 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
32030 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
32040 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
32050 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
32060 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
32070 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
32080 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
32090 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
320a0 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
320b0 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
320c0 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
320d0 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
320e0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
320f0 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
32100 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
32110 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
32120 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
32130 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
32140 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32150 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
32160 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
32170 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a  NULL pointer .**
32180 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c   when first call
32190 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20  ed if N is less 
321a0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
321b0 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
321c0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
321d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
321e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
321f0 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
32200 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
32210 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32220 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
32230 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
32240 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
32250 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
32260 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
32270 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
32280 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
32290 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
322a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
322b0 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
322c0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
322d0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
322e0 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
322f0 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
32300 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57  allocation.)^  W
32310 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c  ithin the xFinal
32320 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73   callback, it is
32330 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65   customary to se
32340 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c  t.** N=0 in call
32350 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  s to sqlite3_agg
32360 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
32370 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a  ,N) so that no .
32380 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d  ** pointless mem
32390 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
323a0 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  occur..**.** ^SQ
323b0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
323c0 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
323d0 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
323e0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
323f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
32400 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
32410 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
32420 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
32430 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
32440 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
32450 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
32460 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
32470 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
32480 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
32490 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
324a0 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
324b0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
324c0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
324d0 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
324e0 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
324f0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
32500 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
32510 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
32520 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
32530 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
32540 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
32550 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
32560 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
32570 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
32580 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
32590 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
325a0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
325b0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
325c0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
325d0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
325e0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
325f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
32600 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
32610 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
32620 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
32630 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
32640 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
32650 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
32660 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32670 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
32680 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32690 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
326a0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
326b0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
326c0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
326d0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
326e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
326f0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
32700 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
32710 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
32720 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
32730 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32740 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32750 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
32760 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
32770 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
32780 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
32790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
327a0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
327b0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
327c0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
327d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
327e0 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
327f0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
32800 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
32810 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
32820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32830 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
32840 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
32850 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32860 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
32870 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
32880 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
32890 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
328a0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
328b0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
328c0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
328d0 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  unction..*/.SQLI
328e0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a  TE_API sqlite3 *
328f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
32900 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
32910 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
32920 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
32930 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
32940 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73   Data.**.** Thes
32950 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  e functions may 
32960 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d  be used by (non-
32970 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66  aggregate) SQL f
32980 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
32990 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
329a0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
329b0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
329c0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
329d0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
329e0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
329f0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
32a00 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
32a10 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
32a20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
32a30 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
32a40 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
32a50 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
32a60 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rved.  An exampl
32a70 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68  e.** of where th
32a80 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66  is might be usef
32a90 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c  ul is in a regul
32aa0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
32ab0 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  tching.** functi
32ac0 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
32ad0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
32ae0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
32af0 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  on can be stored
32b00 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
32b10 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32b20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
32b30 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73  ng.  .** Then as
32b40 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74   long as the pat
32b50 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61  tern string rema
32b60 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a  ins the same,.**
32b70 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   the compiled re
32b80 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
32b90 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
32ba0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
32bb0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
32bc0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a   same function..
32bd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32be0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
32bf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32c00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
32c10 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
32c20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
32c30 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
32c40 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
32c50 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
32c60 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
32c70 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
32c80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32c90 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69  ion. ^If there i
32ca0 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a  s no metadata.**
32cb0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32cc0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72   the function ar
32cd0 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c  gument, this sql
32ce0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
32cf0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
32d00 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
32d10 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
32d20 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
32d30 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
32d40 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
32d50 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f  P as metadata fo
32d60 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
32d70 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
32d80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32d90 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75  d function.  ^Su
32da0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
32db0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
32dc0 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65  _auxdata(C,N) re
32dd0 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20  turn P from the 
32de0 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
32df0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32e00 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c  ta(C,N,P,X) call
32e10 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
32e20 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20   is still valid 
32e30 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68  or.** NULL if th
32e40 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  e metadata has b
32e50 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  een discarded..*
32e60 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61  * ^After each ca
32e70 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
32e80 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
32e90 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f  X) where X is no
32ea0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74  t NULL,.** SQLit
32eb0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
32ec0 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
32ed0 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72  ction X with par
32ee0 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79  ameter P exactly
32ef0 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74  .** once, when t
32f00 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
32f10 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c  iscarded..** SQL
32f20 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64  ite is free to d
32f30 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64  iscard the metad
32f40 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c  ata at any time,
32f50 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e   including: <ul>
32f60 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68  .** <li> when th
32f70 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
32f80 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
32f90 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a  er changes, or.*
32fa0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c  * <li> when [sql
32fb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
32fc0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
32fd0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ze()] is called 
32fe0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
32ff0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f  SQL statement, o
33000 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73  r.** <li> when s
33010 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33020 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ta() is invoked 
33030 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d  again on the sam
33040 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a  e parameter, or.
33050 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74  ** <li> during t
33060 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69  he original sqli
33070 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33080 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65  ) call when a me
33090 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c  mory .**      al
330a0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
330b0 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a  ccurs. </ul>)^.*
330c0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61  *.** Note the la
330d0 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72  st bullet in par
330e0 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65  ticular.  The de
330f0 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a  structor X in .*
33100 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
33110 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d  xdata(C,N,P,X) m
33120 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69  ight be called i
33130 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
33140 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  re the.** sqlite
33150 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
33160 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72  interface even r
33170 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73  eturns.  Hence s
33180 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33190 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  ta().** should b
331a0 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68  e called near th
331b0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e  e end of the fun
331c0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
331d0 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20  tion and the.** 
331e0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
331f0 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ntation should n
33200 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20  ot make any use 
33210 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71  of P after.** sq
33220 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33230 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c  a() has been cal
33240 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  led..**.** ^(In 
33250 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
33260 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
33270 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
33280 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75   calls for.** fu
33290 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
332a0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69  s that are compi
332b0 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74  le-time constant
332c0 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74  s, including lit
332d0 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
332e0 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  nd [parameters] 
332f0 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20  and expressions 
33300 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68  composed from th
33310 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e same.)^.**.** 
33320 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
33330 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
33340 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
33350 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
33360 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33370 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
33380 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
33390 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
333a0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
333b0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  ext*, int N);.SQ
333c0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
333d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
333e0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
333f0 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
33400 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
33410 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
33420 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
33430 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
33440 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
33450 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
33460 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
33470 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
33480 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
33490 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
334a0 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
334b0 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
334c0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
334d0 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
334e0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
334f0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
33500 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
33510 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
33520 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
33530 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
33540 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
33550 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
33560 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
33570 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
33580 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
33590 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
335a0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
335b0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
335c0 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
335d0 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
335e0 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
335f0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
33600 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
33610 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
33620 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
33630 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
33640 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
33650 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
33660 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
33670 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
33680 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
33690 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
336a0 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
336b0 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
336c0 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
336d0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
336e0 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
336f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
33700 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
33710 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
33720 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
33730 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
33740 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
33750 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
33760 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33770 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
33780 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
33790 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
337a0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
337b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
337c0 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
337d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
337e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
337f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
33800 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
33810 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
33820 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
33830 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33840 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
33850 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
33860 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
33870 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
33880 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
33890 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
338a0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
338b0 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
338c0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
338d0 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
338e0 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
338f0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
33900 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
33910 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
33920 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
33930 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
33940 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
33950 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
33960 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33970 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
33980 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
33990 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
339a0 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
339b0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
339c0 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
339d0 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
339e0 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
339f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
33a00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33a10 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
33a20 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
33a30 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
33a40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33a50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33a60 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
33a70 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
33a80 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
33a90 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
33aa0 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
33ab0 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
33ac0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
33ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33ae0 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
33af0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33b00 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
33b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33b20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33b30 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
33b40 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
33b50 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
33b60 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
33b70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33b80 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
33b90 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33ba0 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
33bb0 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
33bc0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
33bd0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
33be0 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
33bf0 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
33c00 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
33c10 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
33c20 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
33c30 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
33c40 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
33c50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33c60 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
33c70 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
33c80 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
33c90 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
33ca0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
33cb0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
33cc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33cd0 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
33ce0 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
33cf0 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
33d00 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
33d10 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
33d20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
33d30 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
33d40 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
33d50 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
33d60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33d70 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
33d80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33d90 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
33da0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
33db0 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
33dc0 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
33dd0 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
33de0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
33df0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
33e00 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
33e10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
33e20 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
33e30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
33e40 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
33e50 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
33e60 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
33e70 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
33e80 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
33e90 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
33ea0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
33eb0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
33ec0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33ed0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
33ee0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33ef0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
33f00 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
33f10 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
33f20 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
33f30 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
33f40 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
33f50 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
33f60 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
33f70 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
33f80 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
33f90 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
33fa0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
33fb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33fc0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
33fd0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
33fe0 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
33ff0 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
34000 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
34010 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
34020 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
34030 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
34040 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
34050 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
34060 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
34070 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
34080 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
34090 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
340a0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
340b0 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
340c0 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
340d0 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
340e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
340f0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
34100 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
34110 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
34120 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
34130 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
34140 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
34150 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
34160 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
34170 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34180 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
34190 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
341a0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
341b0 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
341c0 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
341d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
341e0 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
341f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34200 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
34210 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
34220 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
34230 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34240 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34250 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
34260 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
34270 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
34280 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
34290 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
342a0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
342b0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
342c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
342d0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
342e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
342f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
34300 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
34310 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
34320 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
34330 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
34340 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34350 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
34360 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34370 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
34380 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34390 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
343a0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
343b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
343c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
343d0 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
343e0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
343f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34400 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
34410 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34420 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
34430 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
34440 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
34450 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34460 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34470 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
34480 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
34490 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
344a0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
344b0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
344c0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
344d0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
344e0 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
344f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
34500 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
34510 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
34520 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34530 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
34540 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
34550 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34560 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34570 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
34580 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
34590 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
345a0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
345b0 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
345c0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
345d0 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
345e0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
345f0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
34600 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
34610 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
34620 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
34630 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34640 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34650 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
34660 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
34670 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
34680 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
34690 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
346a0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
346b0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
346c0 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
346d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
346e0 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
346f0 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66  tion result.  If
34700 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
34710 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  er is non-negati
34720 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d  ve, then it.** m
34730 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
34740 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20  offset into the 
34750 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65  string where the
34760 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
34770 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20  would.** appear 
34780 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  if the string wh
34790 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  ere NUL terminat
347a0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
347b0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
347c0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e  .** in the strin
347d0 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73  g at a byte offs
347e0 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  et that is less 
347f0 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  than the value o
34800 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72  f the 3rd.** par
34810 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
34820 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
34830 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65  g will contain e
34840 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64  mbedded NULs and
34850 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f   the.** result o
34860 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70  f expressions op
34870 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e  erating on strin
34880 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  gs with embedded
34890 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
348a0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  ed..** ^If the 4
348b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
348c0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
348d0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
348e0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
348f0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
34900 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
34910 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
34920 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
34930 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
34940 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
34950 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
34960 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
34970 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
34980 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
34990 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
349a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
349b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
349c0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
349d0 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
349e0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
349f0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
34a00 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
34a10 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
34a20 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
34a30 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
34a40 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
34a50 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
34a60 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
34a70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
34a80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
34a90 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
34aa0 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
34ab0 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
34ac0 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
34ad0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
34ae0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
34af0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
34b00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34b10 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
34b20 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
34b30 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
34b40 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
34b50 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
34b60 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
34b70 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
34b80 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
34b90 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
34ba0 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
34bb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
34bc0 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
34bd0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
34be0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
34bf0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
34c00 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
34c10 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
34c20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34c30 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
34c40 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
34c50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34c60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
34c70 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
34c80 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
34c90 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
34ca0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
34cb0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
34cc0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
34cd0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
34ce0 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
34cf0 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
34d00 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
34d10 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
34d20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
34d30 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
34d40 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34d50 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
34d60 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70  t harm..** ^A [p
34d70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34d80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
34d90 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
34da0 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
34db0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
34dc0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34dd0 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
34de0 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
34df0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
34e00 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
34e10 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
34e20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
34e30 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
34e40 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
34e50 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
34e60 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
34e70 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
34e80 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
34e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34ea0 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
34eb0 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
34ec0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
34ed0 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
34ee0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
34ef0 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
34f00 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34f10 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
34f20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
34f30 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
34f40 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
34f50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
34f60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34f70 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
34f80 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
34f90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
34fa0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34fb0 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
34fc0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
34fd0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  char*, int);.SQL
34fe0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
34ff0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35000 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
35010 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
35020 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
35030 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35040 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
35050 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
35060 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
35070 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
35080 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
35090 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
350a0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
350b0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
350c0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
350d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
350e0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
350f0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
35100 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
35110 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35120 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
35130 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35140 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
35150 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
35160 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
35170 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
35180 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
35190 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
351a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
351b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
351c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
351d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
351e0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
351f0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
35200 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
35210 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35220 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35230 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
35240 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
35250 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
35260 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35270 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
35280 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35290 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
352a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
352b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
352c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
352d0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
352e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
352f0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
35300 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
35310 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35320 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
35330 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35340 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
35350 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
35360 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35370 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
35380 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
35390 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
353a0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
353b0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
353c0 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
353d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
353e0 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
353f0 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
35400 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
35410 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
35420 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35430 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
35440 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
35450 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
35460 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
35470 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
35480 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
35490 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
354a0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
354b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
354c0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
354d0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
354e0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
354f0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
35500 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35510 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
35520 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
35530 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
35540 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
35550 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
35560 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
35570 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
35580 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
35590 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
355a0 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
355b0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
355c0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
355d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
355e0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
355f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
35600 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
35610 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
35620 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35630 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
35640 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
35650 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
35660 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
35670 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
35680 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
35690 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
356a0 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
356b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
356c0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
356d0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
356e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
356f0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
35700 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
35710 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
35720 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
35730 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
35740 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35750 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
35760 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
35770 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
35780 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
35790 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
357a0 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
357b0 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
357c0 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
357d0 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
357e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
357f0 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
35800 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
35810 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
35820 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
35830 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35840 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
35850 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
35860 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
35870 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
35880 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
35890 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
358a0 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
358b0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
358c0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
358d0 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
358e0 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
358f0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
35900 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
35910 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
35920 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
35930 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
35940 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
35950 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
35960 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
35970 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
35980 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
35990 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
359a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
359b0 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
359c0 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
359d0 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
359e0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
359f0 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
35a00 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
35a10 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
35a20 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
35a30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35a40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
35a50 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
35a60 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
35a70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
35a80 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
35a90 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
35aa0 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
35ab0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
35ac0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
35ad0 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
35ae0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
35af0 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
35b00 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
35b10 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
35b20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
35b30 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
35b40 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
35b50 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
35b60 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
35b70 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
35b80 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
35b90 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
35ba0 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
35bb0 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
35bc0 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
35bd0 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
35be0 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
35bf0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
35c00 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
35c10 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
35c20 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
35c30 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
35c40 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
35c50 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
35c60 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
35c70 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
35c80 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
35c90 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
35ca0 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
35cb0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
35cc0 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
35cd0 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
35ce0 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
35cf0 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
35d00 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
35d10 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
35d20 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
35d30 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
35d40 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
35d50 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
35d60 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
35d70 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
35d80 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
35d90 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
35da0 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
35db0 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
35dc0 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
35dd0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
35de0 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
35df0 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
35e00 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
35e10 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
35e20 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
35e30 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
35e40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35e50 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35e60 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
35e70 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
35e80 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
35e90 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
35ea0 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
35eb0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
35ec0 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
35ed0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
35ee0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
35ef0 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
35f00 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35f10 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
35f20 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
35f30 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
35f40 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
35f50 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
35f60 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
35f70 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
35f80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35f90 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
35fa0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
35fb0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
35fc0 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
35fd0 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
35fe0 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
35ff0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
36000 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36010 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
36020 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
36030 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
36040 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36050 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
36060 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
36070 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
36080 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
36090 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
360a0 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
360b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
360c0 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
360d0 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
360e0 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
360f0 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
36100 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
36110 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
36120 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
36130 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
36140 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
36150 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
36160 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
36170 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
36180 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
36190 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
361a0 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
361b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
361c0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
361d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
361e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
361f0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
36200 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
36210 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
36220 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
36230 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
36240 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
36250 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
36260 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
36270 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
36280 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
36290 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
362a0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c  st void*).);.SQL
362b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
362c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
362d0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
362e0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
362f0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
36300 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
36310 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
36320 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
36330 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
36340 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
36350 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
36360 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
36370 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36380 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36390 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
363a0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
363b0 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
363c0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
363d0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
363e0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
363f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36400 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36410 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
36420 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
36430 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
36440 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
36450 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
36460 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
36470 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
36480 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
36490 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
364a0 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
364b0 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
364c0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
364d0 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
364e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
364f0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
36500 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
36510 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
36520 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
36530 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
36540 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
36550 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
36560 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
36570 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
36580 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
36590 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
365a0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
365b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
365c0 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
365d0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
365e0 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
365f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36600 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
36610 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
36620 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
36630 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
36640 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
36650 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
36660 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
36670 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
36680 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
36690 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
366a0 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
366b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
366c0 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
366d0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
366e0 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
366f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
36700 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
36710 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
36720 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
36730 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
36740 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
36750 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
36760 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
36770 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
36780 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
36790 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
367a0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
367b0 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
367c0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
367d0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
367e0 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
367f0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
36800 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
36810 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
36820 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
36830 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
36840 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
36850 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
36860 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
36870 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
36880 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
36890 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
368a0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
368b0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
368c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
368d0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
368e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
368f0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
36900 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36910 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
36920 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36930 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
36940 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
36950 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
36960 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
36970 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
36980 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
36990 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
369a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
369b0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
369c0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
369d0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
369e0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
369f0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
36a00 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69  st void*).);..#i
36a10 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f  fdef SQLITE_HAS_
36a20 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CODEC./*.** Spec
36a30 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
36a40 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
36a50 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
36a60 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
36a70 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
36a80 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
36a90 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
36aa0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
36ab0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
36ac0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
36ad0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
36ae0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
36af0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
36b00 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
36b10 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36b20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36b30 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
36b40 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36b50 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
36b60 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
36b70 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53 51  The key */.);.SQ
36b80 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
36b90 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73  ite3_key_v2(.  s
36ba0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
36bb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36bc0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
36bd0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
36be0 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
36bf0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
36c00 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
36c10 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  ase */.  const v
36c20 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
36c30 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
36c40 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
36c50 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
36c60 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
36c70 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
36c80 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
36c90 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
36ca0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
36cb0 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
36cc0 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
36cd0 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
36ce0 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
36cf0 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
36d00 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
36d10 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
36d20 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
36d30 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
36d40 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
36d50 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
36d60 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
36d70 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36d80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36d90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
36da0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
36db0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
36dc0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
36dd0 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
36de0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
36df0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
36e00 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  y_v2(.  sqlite3 
36e10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
36e20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
36e30 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
36e40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
36e50 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
36e60 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
36e70 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  the database */.
36e80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
36e90 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
36ea0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
36eb0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
36ec0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
36ed0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
36ee0 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
36ef0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
36f00 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
36f10 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
36f20 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   work..*/.SQLITE
36f30 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
36f40 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
36f50 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
36f60 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
36f70 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
36f80 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
36f90 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
36fa0 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
36fb0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
36fc0 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
36fd0 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
36fe0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
36ff0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
37000 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
37010 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
37020 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
37030 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63   void sqlite3_ac
37040 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
37050 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
37060 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
37070 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
37080 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
37090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
370a0 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
370b0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
370c0 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
370d0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
370e0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
370f0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
37100 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
37110 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
37120 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
37130 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
37140 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
37150 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
37160 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
37170 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
37180 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
37190 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
371a0 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
371b0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
371c0 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
371d0 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
371e0 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
371f0 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
37200 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
37210 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
37220 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
37230 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
37240 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
37250 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
37260 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
37270 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
37280 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
37290 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
372a0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
372b0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
372c0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
372d0 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
372e0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
372f0 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
37300 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
37310 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
37320 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
37330 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
37340 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
37350 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
37360 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
37370 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
37380 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
37390 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49  agraphs..*/.SQLI
373a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
373b0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
373c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
373d0 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
373e0 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
373f0 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
37400 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
37410 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
37420 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
37430 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
37440 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
37450 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
37460 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
37470 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
37480 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
37490 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
374a0 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
374b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
374c0 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
374d0 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
374e0 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
374f0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
37500 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
37510 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
37520 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
37530 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
37540 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
37550 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
37560 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
37570 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
37580 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
37590 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
375a0 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
375b0 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
375c0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
375d0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
375e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
375f0 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
37600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
37610 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
37620 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
37630 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
37640 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
37650 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
37660 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
37670 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
37680 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
37690 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
376a0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
376b0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
376c0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
376d0 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
376e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
376f0 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
37700 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
37710 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
37720 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
37730 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
37740 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
37750 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
37760 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
37770 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
37780 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
37790 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
377a0 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
377b0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
377c0 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
377d0 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
377e0 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
377f0 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
37800 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
37810 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
37820 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
37830 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
37840 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
37850 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
37860 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
37870 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
37880 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
37890 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
378a0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
378b0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
378c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
378d0 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
378e0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
378f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
37900 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
37910 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
37920 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
37930 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
37940 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
37950 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   avoided..**.** 
37960 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
37970 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
37980 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
37990 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
379a0 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
379b0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b  ior to calling [
379c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72  sqlite3_open] or
379d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
379e0 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  2].  Otherwise, 
379f0 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
37a00 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
37a10 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
37a20 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
37a30 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20 61  fail.  Here is a
37a40 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20  n.** example of 
37a50 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20 75  how to do this u
37a60 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74 68  sing C++ with th
37a70 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  e Windows Runtim
37a80 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  e:.**.** <blockq
37a90 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50  uote><pre>.** LP
37aa0 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57 69  CWSTR zPath = Wi
37ab0 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a  ndows::Storage::
37ac0 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a  ApplicationData:
37ad0 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e  :Current->.** &n
37ae0 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72 61  bsp;     Tempora
37af0 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d 3e  ryFolder->Path->
37b00 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72 20  Data();.** char 
37b10 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41 58  zPathBuf&#91;MAX
37b20 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b 0a  _PATH + 1&#93;;.
37b30 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68 42  ** memset(zPathB
37b40 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a 50  uf, 0, sizeof(zP
37b50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69 64  athBuf));.** Wid
37b60 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74 65  eCharToMultiByte
37b70 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50 61  (CP_UTF8, 0, zPa
37b80 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75 66  th, -1, zPathBuf
37b90 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75  , sizeof(zPathBu
37ba0 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  f),.** &nbsp;   
37bb0 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a    NULL, NULL);.*
37bc0 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64  * sqlite3_temp_d
37bd0 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69 74  irectory = sqlit
37be0 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22 2c  e3_mprintf("%s",
37bf0 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20 3c   zPathBuf);.** <
37c00 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
37c10 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e>.*/.SQLITE_API
37c20 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63   SQLITE_EXTERN c
37c30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
37c40 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
37c50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
37c60 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
37c70 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61 73   Holding Databas
37c80 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  e Files.**.** ^(
37c90 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
37ca0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
37cb0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
37cc0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
37cd0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
37ce0 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
37cf0 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
37d00 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ll database file
37d10 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 77  s.** specified w
37d20 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70  ith a relative p
37d30 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65 61  athname and crea
37d40 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64 20  ted or accessed 
37d50 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68 65  by.** SQLite whe
37d60 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
37d70 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69  in windows [sqli
37d80 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20 77  te3_vfs | VFS] w
37d90 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a 2a  ill be assumed.*
37da0 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76 65  * to be relative
37db0 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74 6f   to that directo
37dc0 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20 76  ry.)^ ^If this v
37dd0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
37de0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68  L.** pointer, th
37df0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
37e00 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61 62  s that all datab
37e10 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69 66  ase files specif
37e20 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72 65  ied.** with a re
37e30 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20  lative pathname 
37e40 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20  are relative to 
37e50 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
37e60 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65  ctory.** for the
37e70 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20   process.  Only 
37e80 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
37e90 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68 69  makes use of thi
37ea0 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69  s global.** vari
37eb0 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e 6f  able; it is igno
37ec0 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78 20  red by the unix 
37ed0 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67  VFS..**.** Chang
37ee0 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ing the value of
37ef0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77   this variable w
37f00 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65 20  hile a database 
37f10 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a  connection is.**
37f20 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c 74   open can result
37f30 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64 61   in a corrupt da
37f40 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74  tabase..**.** It
37f50 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
37f60 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
37f70 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
37f80 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
37f90 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
37fa0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
37fb0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
37fc0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
37fd0 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
37fe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37ff0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
38000 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
38010 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
38020 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
38030 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
38040 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
38050 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
38060 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
38070 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
38080 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
38090 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
380a0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
380b0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
380c0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
380d0 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
380e0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
380f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64  r..**.** ^The [d
38100 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
38110 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
38120 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
38130 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
38140 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
38150 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
38160 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38170 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
38180 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64  rmore,.** the [d
38190 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
381a0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
381b0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
381c0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
381d0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
381e0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
381f0 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
38200 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
38210 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
38220 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
38230 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
38240 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
38250 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
38260 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
38270 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
38280 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
38290 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
382a0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
382b0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
382c0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
382d0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
382e0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
382f0 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
38300 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  he use of the [d
38310 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
38320 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
38330 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
38340 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  /.SQLITE_API SQL
38350 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
38360 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64 69  *sqlite3_data_di
38370 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
38380 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
38390 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
383a0 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
383b0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
383c0 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
383d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
383e0 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
383f0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
38400 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
38410 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
38420 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
38430 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
38440 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
38450 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
38460 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
38470 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
38480 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
38490 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
384a0 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
384b0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
384c0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
384d0 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
384e0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
384f0 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
38500 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
38510 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
38520 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
38530 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
38540 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
38550 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
38560 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
38570 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
38580 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
38590 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
385a0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
385b0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
385c0 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
385d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
385e0 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
385f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
38600 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
38610 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
38620 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
38630 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
38640 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
38650 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
38660 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
38670 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
38680 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
38690 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
386a0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
386b0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
386c0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
386d0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
386e0 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
386f0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
38700 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
38710 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
38720 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
38730 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
38740 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
38750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38760 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
38770 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
38780 65 70 61 72 65 64 20 53 74 61 74 65 6d