System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact c770d36b159a40ca6950a8992f6ef0148635e3b4:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 31 37 22 0a 23 64 65 66 69 6e 65 20 53  .7.17".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 37 0a 23 64 65  MBER 3007017.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33  CE_ID      "2013
1070: 2d 30 35 2d 31 36 20 31 32 3a 34 31 3a 34 39 20  -05-16 12:41:49 
1080: 36 64 34 35 61 37 39 66 62 31 38 64 63 64 33 30  6d45a79fb18dcd30
1090: 35 63 63 34 31 63 35 32 35 30 36 30 65 34 32 66  5cc41c525060e42f
10a0: 32 34 30 32 62 64 37 37 22 0a 0a 2f 2a 0a 2a 2a  2402bd77"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2fc0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2fd0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2fe0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2ff0: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
3000: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f   handles], and/o
3030: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61  r.** [sqlite3_ba
3040: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68  ckup] objects th
3050: 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 51  en it returns SQ
3060: 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20  LITE_OK but the 
3070: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
3080: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
3090: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
30a0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
30b0: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
30c0: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
30d0: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
30e0: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
30f0: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
3100: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
3110: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
3120: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
3130: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3140: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
3150: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
3160: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
3170: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
3180: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
3190: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
31a0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31b0: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
31c0: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
31d0: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
31e0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
31f0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
3200: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
3210: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
3220: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
3230: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
3240: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
3250: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
3260: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
3270: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
3280: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
3290: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
32a0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
32b0: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
32c0: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
32d0: 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  op..*/.SQLITE_AP
32e0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  I int sqlite3_cl
32f0: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  ose(sqlite3*);.S
3300: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3320: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3330: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3340: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3350: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
3360: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
3370: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
3380: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
3390: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
33a0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
33b0: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
33c0: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
33d0: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
33e0: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
33f0: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3400: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3410: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3420: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3430: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
3440: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
3450: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63   is a convenienc
3460: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  e wrapper around
3470: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
3480: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
3490: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
34a0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
34b0: 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20  ize()],.** that 
34c0: 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63  allows an applic
34d0: 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c  ation to run mul
34e0: 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73  tiple statements
34f0: 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f   of SQL.** witho
3500: 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65  ut having to use
3510: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65   a lot of C code
3520: 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  . .**.** ^The sq
3530: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
3540: 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f  erface runs zero
3550: 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65   or more UTF-8 e
3560: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63  ncoded,.** semic
3570: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51  olon-separate SQ
3580: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3590: 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64  sed into its 2nd
35a0: 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e   argument,.** in
35b0: 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20   the context of 
35c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35d0: 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64  nnection] passed
35e0: 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a   in as its 1st.*
35f0: 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66  * argument.  ^If
3600: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
3610: 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72  nction of the 3r
3620: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
3630: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3640: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
3650: 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  n it is invoked 
3660: 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20  for each result 
3670: 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75  row.** coming ou
3680: 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74  t of the evaluat
3690: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
36a0: 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67  s.  ^The 4th arg
36b0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65  te3_exec() is re
36d0: 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f  layed through to
36e0: 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e   the 1st argumen
36f0: 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c  t of each.** cal
3700: 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e  lback invocation
3710: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
3720: 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ack pointer to s
3730: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3740: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e   is NULL, then n
3750: 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76  o callback is ev
3760: 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72  er invoked and r
3770: 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a  esult rows are.*
3780: 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  * ignored..**.**
3790: 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
37a0: 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75  curs while evalu
37b0: 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74  ating the SQL st
37c0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
37d0: 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
37e0: 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65  exec(), then exe
37f0: 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  cution of the cu
3800: 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20  rrent statement 
3810: 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62  stops and.** sub
3820: 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e  sequent statemen
3830: 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20  ts are skipped. 
3840: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3850: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3860: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e  3_exec().** is n
3870: 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79  ot NULL then any
3880: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
3890: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  s written into m
38a0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a  emory obtained.*
38b0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
38c0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61  malloc()] and pa
38d0: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67  ssed back throug
38e0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
38f0: 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ter..** To avoid
3900: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74   memory leaks, t
3910: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
3920: 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71  hould invoke [sq
3930: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
3940: 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   on error messag
3950: 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
3960: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
3970: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a  th parameter of.
3980: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  ** of sqlite3_ex
3990: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
39a0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
39b0: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
39c0: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
39d0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
39e0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
39f0: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3a00: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3a10: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3a30: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3a40: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3a50: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3a60: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3a70: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3a90: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3aa0: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3ab0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3ac0: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3ad0: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3ae0: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3af0: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3b00: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3b10: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3b20: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3b30: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3b40: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3b50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3b60: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3b70: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3b80: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3b90: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3ba0: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3bb0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3bc0: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3bd0: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3be0: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3bf0: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3c00: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3c10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3c20: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3c30: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3c40: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3c50: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3c60: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3c70: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3c80: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3c90: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3ca0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3cb0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3cc0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3cd0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3ce0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3cf0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3d00: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3d10: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3d20: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3d30: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3d40: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3d50: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3d60: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3d70: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3d80: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3d90: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3da0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3db0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3dc0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3dd0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3de0: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3df0: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3e00: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3e10: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3e20: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3e30: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3e40: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3e50: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3e60: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3e70: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3e80: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3e90: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
3ea0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3eb0: 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20  ion must insure 
3ec0: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
3ed0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3ee0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
3ef0: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
3f00: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
3f20: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3f30: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
3f40: 73 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  se [database con
3f50: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
3f60: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68  ed by.**      th
3f70: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3f80: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3f90: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3fa0: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3fb0: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  g..** <li> The a
3fc0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3fd0: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53  not modify the S
3fe0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
3ff0: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  t passed into.**
4000: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61        the 2nd pa
4010: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
4020: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
4030: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
4040: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f  s running..** </
4050: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul>.*/.SQLITE_AP
4060: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
4070: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  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: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
40b0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
40c0: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
40f0: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4100: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4110: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4120: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4130: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4140: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 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: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
4180: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
4190: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 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 20 2f 2a 20               /* 
41c0: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
41d0: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
41e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
41f0: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4200: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4210: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4220: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4230: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4240: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4250: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
4260: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
4270: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
4280: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
4290: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
42a0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
42b0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
42c0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
42d0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
42e0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
42f0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4300: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4310: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4320: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4330: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4340: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4350: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
4360: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
4370: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
4380: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
4390: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
43a0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
43b0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
43c0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
43d0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
43e0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4400: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4410: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4420: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4440: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4450: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4460: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4470: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4480: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4490: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
44a0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
44b0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44c0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
44d0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
44e0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44f0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4510: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4520: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4530: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4560: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4570: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4580: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4590: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
45a0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
45b0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
45c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45d0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
45e0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45f0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4600: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4620: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4630: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4640: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4650: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4660: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4670: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4680: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4690: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
46a0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
46b0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
46c0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
46d0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
46e0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46f0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4700: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4710: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4720: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4730: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4760: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4770: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4780: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4790: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47a0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
47b0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
47c0: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
47d0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
47e0: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47f0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4800: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4810: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4830: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4840: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4850: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4860: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4870: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4880: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4890: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
48a0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
48b0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
48c0: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
48d0: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48f0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4900: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4910: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4920: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4930: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4940: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4950: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4970: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4980: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4990: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
49a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49b0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
49c0: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
49d0: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
49e0: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4a00: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4a10: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4a20: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4a30: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4a40: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a50: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a60: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a80: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a90: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4aa0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4ab0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4ad0: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4ae0: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4af0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4b00: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4b20: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4b30: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4b40: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b60: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b70: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b80: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b90: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ba0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4bb0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4bc0: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4bd0: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4be0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bf0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4c00: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4c10: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4c20: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4c30: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4c40: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c50: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c60: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c70: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c80: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4c90: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4ca0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4cb0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4cc0: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4cd0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4ce0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4cf0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4d00: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4d10: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4d20: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4d30: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4d40: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4d50: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d60: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d70: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4d80: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4d90: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4da0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4db0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4dc0: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4dd0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4de0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4df0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4e00: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4e10: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4e20: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e30: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e40: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4e50: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4e60: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4e70: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4e80: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4e90: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4ea0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4eb0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4ec0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4ed0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4ee0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4ef0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4f00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4f10: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4f20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4f30: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4f40: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4f50: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4f60: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4f70: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f80: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4f90: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4fa0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4fb0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4fc0: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4fd0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4fe0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4ff0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
5000: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
5010: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
5020: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
5030: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
5040: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
5050: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
5060: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
5070: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
5080: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
5090: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
50a0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5270: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
5280: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
5290: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
52a0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
52c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52e0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5300: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5340: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
5380: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
53c0: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5400: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5440: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
5480: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
54c0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5540: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5580: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
55c0: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5600: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5640: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5660: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
5670: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
5680: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
5690: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
56a0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
56b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
56c0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
56d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
56e0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
56f0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5700: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5710: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5720: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5740: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
5750: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5760: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5780: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
5790: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
57a0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
57c0: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
57e0: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
57f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5800: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5810: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5820: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5840: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5850: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5860: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5870: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5880: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5890: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
58a0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
58b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
58d0: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
58e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
58f0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5900: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5910: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5920: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5950: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5960: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5970: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5980: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5990: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
59a0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
59b0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
59e0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5a20: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5b30: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b70: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b90: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5bb0: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5bc0: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5bd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5bf0: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5c00: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c10: 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (2<<8))../*.**
5c20: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
5c30: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
5c40: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
5c50: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5c60: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5c70: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5c80: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5c90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5ca0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5cb0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5cc0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5cd0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
5ce0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
5cf0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5d00: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5d10: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
5d20: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
5d30: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5d40: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5d50: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5d60: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5d70: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
5d80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5d90: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5da0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
5db0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5dc0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
5dd0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5de0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5df0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5e00: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5e10: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
5e20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5e30: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5e40: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
5e50: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
5e60: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5e70: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
5e80: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
5e90: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
5ea0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5eb0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
5ec0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ed0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
5ee0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5ef0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5f00: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
5f10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5f20: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
5f30: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5f40: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5f50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
5f60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5f70: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
5f80: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5f90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
5fa0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5fb0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
5fc0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5fd0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5fe0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5ff0: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
6000: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6010: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
6020: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
6030: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
6040: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6050: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
6060: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
6070: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
6080: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6090: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
60a0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
60b0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
60c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
60d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
60e0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
60f0: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
6100: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
6110: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
6120: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6130: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
6140: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6150: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6160: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
6170: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
6180: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6190: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
61a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
61b0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
61c0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
61d0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
61e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
61f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6200: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
6210: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
6220: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
6230: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
6240: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
6250: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
6260: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
6270: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
6280: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
6290: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
62a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
62b0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
62c0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
62d0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
62e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
62f0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6300: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6310: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6320: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6330: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
6340: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
6350: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
6360: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
6370: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
6380: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
6390: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
63a0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
63b0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
63c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
63d0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
63e0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
63f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6400: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6410: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6420: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6430: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6440: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6450: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6460: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6470: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6480: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
6490: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
64a0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
64b0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
64c0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
64d0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
64e0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
64f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6500: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6510: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6520: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6530: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6540: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6550: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6560: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6570: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6580: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
6590: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
65a0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
65b0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
65c0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
65d0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
65e0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
65f0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6600: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6610: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6620: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6630: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6640: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6650: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6660: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6670: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6680: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
6690: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
66a0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
66b0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
66c0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
66d0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
66e0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
66f0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6700: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6710: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6720: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6730: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6740: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
6750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6760: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6770: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6780: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
6790: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
67a0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
67b0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
67c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
67d0: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
67e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
67f0: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6800: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6810: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6820: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6830: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6840: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6850: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6870: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
6880: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6890: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
68a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68b0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
68c0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
68d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
68e0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
68f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6900: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6910: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6920: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6930: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6950: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
6960: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6970: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
6980: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6990: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
69a0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
69b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
69c0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
69d0: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
69e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
69f0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6a00: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
6a10: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
6a20: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6a30: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6a40: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6a50: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
6a60: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6a70: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6a80: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
6a90: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
6aa0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6ab0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
6ac0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
6ad0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6ae0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6af0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6b00: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
6b10: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
6b20: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6b40: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6b50: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6b60: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6b70: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6b80: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6b90: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
6ba0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
6bb0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
6bc0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
6bd0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
6be0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6bf0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6c00: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6c10: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6c20: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6c30: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6c40: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6c50: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6c60: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6c70: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6c80: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
6c90: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
6ca0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
6cb0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
6cc0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
6cd0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
6ce0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6cf0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6d00: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
6d10: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6d20: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6d30: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6d40: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6d50: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6d60: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6d70: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6d80: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6d90: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
6da0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
6db0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6dc0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6dd0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6de0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
6df0: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
6e00: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6e10: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6e20: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6e30: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
6e40: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6e50: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
6e60: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6e70: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6e80: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6e90: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6ea0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6eb0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6ec0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
6ed0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
6ee0: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
6ef0: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
6f00: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
6f10: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6f20: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6f30: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
6f40: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6f50: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6f60: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6f70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6f80: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6f90: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6fa0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6fb0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6fc0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6fd0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6fe0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
6ff0: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
7000: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
7010: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
7020: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7030: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
7040: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
7050: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7060: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
7070: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
7080: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
7090: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
70a0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
70b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
70c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
70d0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
70e0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
70f0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
7100: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
7110: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7120: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
7130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7140: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
7150: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
7160: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
7170: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
7180: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
7190: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
71a0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
71b0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
71c0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
71d0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
71e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
71f0: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
7200: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
7210: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
7220: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
7230: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
7240: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
7250: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
7260: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7270: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
7280: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7290: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
72a0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
72b0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
72c0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
72d0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
72e0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
72f0: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
7300: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
7310: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
7320: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
7330: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
7340: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
7350: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
7360: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
7370: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7380: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
7390: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
73a0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
73b0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
73c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
73d0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
73e0: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
73f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7400: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7410: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7420: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7430: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7440: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7450: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7460: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7470: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7480: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
7490: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
74a0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
74b0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
74c0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
74d0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
74e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
74f0: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7500: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7510: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7520: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7530: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7540: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7550: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7560: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7570: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7580: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
7590: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
75a0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
75b0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
75c0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
75d0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
75e0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
75f0: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7600: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7610: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7620: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7630: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7640: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7650: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7660: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7670: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7680: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
7690: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
76a0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
76b0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
76c0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
76d0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
76e0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
76f0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7700: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7710: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7720: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7730: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7740: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7750: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
7760: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7770: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
7780: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
7790: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
77a0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
77b0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
77c0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
77d0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
77e0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
77f0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7800: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
7810: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7820: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
7830: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
7840: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
7850: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7860: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7880: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
7890: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
78a0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
78b0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
78c0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
78d0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
78e0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
78f0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7900: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
7910: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
7920: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7930: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7940: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7950: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
7960: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
7970: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
7980: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
7990: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
79a0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
79b0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
79c0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
79d0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
79e0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
79f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7a00: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
7a10: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
7a20: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7a30: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7a40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7a50: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
7a60: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7a70: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
7a90: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
7aa0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
7ab0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
7ac0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
7ad0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
7ae0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7af0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7b00: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
7b10: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
7b20: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7b30: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7b40: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7b50: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7b60: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7b70: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7b80: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
7b90: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
7ba0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
7bb0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
7bc0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
7bd0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
7be0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7bf0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7c00: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
7c10: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
7c20: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7c30: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7c40: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7c50: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7c60: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7c70: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7c80: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
7c90: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
7ca0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
7cb0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
7cc0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
7cd0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
7ce0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7cf0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7d00: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7d10: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7d20: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7d30: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7d40: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7d50: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7d60: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7d70: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7d80: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7d90: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7da0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7db0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7dc0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7dd0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7de0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7df0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7e00: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7e10: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7e20: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7e30: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7e40: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7e50: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7e60: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7e70: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7e80: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7e90: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7ea0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7eb0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7ec0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7ed0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7ee0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7ef0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7f00: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7f10: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7f20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7f30: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7f40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7f50: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7f60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7f70: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7f80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7f90: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7fb0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7fc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7fd0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ff0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8000: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8010: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8020: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8030: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8040: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8050: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
8060: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8070: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
8080: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
8090: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
80a0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
80b0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
80c0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
80d0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
80e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
80f0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
8100: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
8110: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
8120: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
8130: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
8140: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
8150: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
8160: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
8170: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
8180: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
8190: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
81a0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
81b0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
81c0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
81d0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
81e0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
81f0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
8200: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
8210: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
8220: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
8230: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
8240: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
8250: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8260: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
8270: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
8280: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
8290: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
82a0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
82b0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
82c0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
82d0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
82e0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
82f0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
8300: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
8310: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
8320: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
8330: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
8340: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
8350: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8360: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
8370: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
8380: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
8390: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
83a0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
83b0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
83c0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
83d0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
83e0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
83f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8400: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8410: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8420: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8430: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8440: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8460: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8470: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
8480: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8490: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
84a0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
84b0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
84c0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
84d0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
84e0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
84f0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8500: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8510: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8520: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8530: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8540: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8550: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8560: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8570: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8580: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
8590: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
85a0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
85b0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
85c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
85d0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
85e0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
85f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8600: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8610: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8620: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8630: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8640: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8650: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8670: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
8680: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
8690: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
86a0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
86b0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
86c0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
86d0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
86e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
86f0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8700: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8710: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8720: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8730: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8740: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8750: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
8760: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8770: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8780: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
8790: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
87a0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
87b0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
87c0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
87d0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69  version 2 */.  i
87e0: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c  nt (*xFetch)(sql
87f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8800: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8810: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20   int iAmt, void 
8820: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78  **pp);.  int (*x
8830: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33  Unfetch)(sqlite3
8840: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8850: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69  int64 iOfst, voi
8860: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  d *p);.  /* Meth
8870: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8880: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8890: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  3 */.  /* Additi
88a0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
88b0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
88c0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
88d0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
88e0: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
88f0: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
8900: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
8910: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8920: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8930: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8940: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8950: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8960: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8970: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8980: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8990: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
89a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
89b0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
89c0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
89d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
89e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
89f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8a00: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8a10: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8a20: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8a30: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8a40: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8a50: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8a60: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
8a70: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
8a80: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
8a90: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
8aa0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
8ab0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
8ac0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8ad0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8ae0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8af0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8b00: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8b10: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
8b20: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
8b30: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
8b40: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
8b50: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e  defined..** <ul>
8b60: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8b70: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8b80: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8b90: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8ba0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
8bb0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
8bc0: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
8bd0: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
8be0: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8bf0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8c00: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8c10: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8c20: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8c30: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8c40: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8c50: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8c60: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
8c70: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
8c80: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8c90: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8ca0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8cb0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8cc0: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8cd0: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8ce0: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8cf0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8d00: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8d10: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8d20: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
8d30: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8d40: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8d50: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8d60: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
8d70: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
8d80: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
8d90: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8da0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
8db0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
8dc0: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
8dd0: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
8de0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
8df0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8e00: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
8e10: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
8e20: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
8e30: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
8e40: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
8e50: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
8e60: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
8e70: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
8e80: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
8e90: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
8ea0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
8eb0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
8ec0: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
8ed0: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
8ee0: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
8ef0: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
8f00: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
8f10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8f20: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
8f30: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8f40: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8f50: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8f60: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
8f70: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
8f80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
8f90: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
8fa0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
8fb0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
8fc0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
8fd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8fe0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
8ff0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
9000: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
9010: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
9020: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9030: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
9040: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
9050: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9060: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20  TTED] opcode is 
9070: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9080: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74  ally by.** SQLit
9090: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c  e and sent to al
90a0: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65  l VFSes in place
90b0: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68   of a call to th
90c0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a  e xSync method.*
90d0: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  * when the datab
90e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  ase connection h
90f0: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  as [PRAGMA synch
9100: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f  ronous] set to O
9110: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70  FF.)^.** Some sp
9120: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
9130: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9140: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65   in order to ope
9150: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a  rate correctly.*
9160: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73  * when [PRAGMA s
9170: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9180: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
9190: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74  OFF] is set, but
91a0: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20   most .** VFSes 
91b0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
91c0: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75   signal and shou
91d0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
91e0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  re this opcode..
91f0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
9200: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9210: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9220: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9230: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20  is.** opcode as 
9240: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
9250: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
9260: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9270: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74  lized VFSes.** t
9280: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
9290: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
92a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
92b0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
92c0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
92d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
92e0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
92f0: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9300: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9310: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9320: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9330: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9340: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9350: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
9360: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
9370: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
9380: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
9390: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
93a0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
93b0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
93c0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
93d0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
93e0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
93f0: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9400: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9410: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9420: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9430: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9440: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9450: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9460: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9470: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9480: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
9490: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
94a0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
94b0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
94c0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
94d0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
94e0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
94f0: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9500: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9510: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9520: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9530: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9540: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9550: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9560: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9570: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9580: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
9590: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
95a0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
95b0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
95c0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
95d0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
95e0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
95f0: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9600: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9610: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9620: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9630: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9640: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9650: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9660: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9670: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9680: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9690: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
96a0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
96b0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
96c0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
96d0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
96e0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
96f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9700: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9710: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9720: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9730: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9740: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9750: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9760: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
9770: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
9780: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
9790: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
97a0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
97b0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
97c0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
97d0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
97e0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
97f0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9800: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9810: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9820: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9830: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9840: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9850: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
9860: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
9870: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
9880: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
9890: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
98a0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
98b0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
98c0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
98d0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
98e0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
98f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9900: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9910: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9920: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9930: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
9940: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9950: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
9960: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
9970: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
9980: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
9990: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
99a0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
99b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
99c0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
99d0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
99e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
99f0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9a00: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9a10: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
9a20: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
9a30: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
9a40: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
9a50: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9a60: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
9a70: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
9a80: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9a90: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
9aa0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
9ab0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9ac0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9ad0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9ae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9af0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9b00: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9b10: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9b20: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9b30: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
9b40: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
9b50: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
9b60: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
9b70: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
9b80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
9b90: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9ba0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
9bb0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
9bc0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
9bd0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
9be0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9bf0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9c00: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9c10: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9c20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9c30: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9c40: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9c50: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
9c60: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
9c70: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
9c80: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
9c90: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9ca0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
9cb0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
9cc0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9cd0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9ce0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
9cf0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9d00: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
9d10: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9d20: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
9d30: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
9d40: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
9d50: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
9d60: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
9d70: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
9d80: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
9d90: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
9da0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
9db0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
9dc0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
9dd0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
9de0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
9df0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
9e00: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
9e10: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
9e20: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9e30: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9e40: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9e50: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9e60: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
9e70: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
9e80: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
9e90: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
9ea0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
9eb0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
9ec0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
9ed0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
9ee0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
9ef0: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
9f00: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
9f10: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
9f20: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
9f30: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
9f40: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
9f50: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
9f60: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
9f70: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
9f80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9f90: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
9fa0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
9fb0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
9fc0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
9fd0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
9fe0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
9ff0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a000: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a010: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a020: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a030: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a040: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a050: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a060: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a070: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a080: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a090: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a0a0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a0b0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a0c0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a0d0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a0e0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a0f0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a100: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
a110: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
a120: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a130: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
a140: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a150: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
a160: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
a170: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
a180: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
a190: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
a1a0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
a1b0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
a1c0: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
a1d0: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
a1e0: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
a1f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a200: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a210: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
a220: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
a230: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
a240: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
a250: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
a260: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
a270: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
a280: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
a290: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
a2a0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
a2b0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
a2c0: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
a2d0: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
a2e0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
a2f0: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
a300: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a310: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a320: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
a330: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
a340: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
a350: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
a360: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
a370: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
a380: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
a390: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
a3a0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
a3b0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
a3c0: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
a3d0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
a3e0: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
a3f0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
a400: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
a410: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
a420: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a430: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a440: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
a450: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
a460: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
a470: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
a480: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
a490: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a4a0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a4b0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a4c0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
a4d0: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
a4e0: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
a4f0: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
a500: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
a510: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
a520: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
a530: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
a540: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
a550: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a560: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a570: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
a580: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
a590: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
a5a0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
a5b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a5c0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
a5d0: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
a5e0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
a5f0: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
a600: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
a610: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
a620: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
a630: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
a640: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
a650: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a660: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
a670: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
a680: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
a690: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
a6a0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
a6b0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
a6c0: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
a6d0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
a6e0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
a6f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
a700: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
a710: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a720: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
a730: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
a740: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
a750: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
a760: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
a770: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
a780: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
a790: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
a7a0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
a7b0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
a7c0: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
a7d0: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
a7e0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
a7f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
a800: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
a810: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
a820: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
a830: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
a840: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
a850: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
a860: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
a870: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
a880: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
a890: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
a8a0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
a8b0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
a8c0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
a8d0: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
a8e0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
a8f0: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
a900: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
a910: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
a920: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
a930: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
a940: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
a950: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
a960: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
a970: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
a980: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
a990: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
a9a0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
a9b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
a9c0: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
a9d0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
a9e0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
a9f0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
aa00: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
aa10: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
aa20: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
aa30: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
aa40: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
aa50: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
aa60: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
aa70: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
aa80: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
aa90: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
aaa0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
aab0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
aac0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
aad0: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
aae0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
aaf0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
ab00: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
ab10: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
ab20: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
ab30: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
ab40: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
ab50: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
ab60: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
ab70: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
ab80: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
ab90: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
aba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
abb0: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
abc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
abd0: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
abe0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
abf0: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
ac00: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
ac10: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
ac20: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
ac30: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
ac40: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
ac50: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
ac60: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
ac70: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
ac80: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
ac90: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
aca0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
acb0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
acc0: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
acd0: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
ace0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
acf0: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
ad00: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
ad10: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
ad20: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
ad30: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
ad40: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
ad50: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
ad60: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
ad70: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
ad80: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
ad90: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
ada0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
adb0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
adc0: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
add0: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
ade0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
adf0: 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ..**.** </ul>.*/
ae00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ae10: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
ae20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
ae30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
ae40: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ae50: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
ae60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
ae70: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
ae80: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
ae90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
aea0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
aeb0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
aec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
aed0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
aee0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
aef0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
af00: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
af10: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
af20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
af30: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
af40: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
af50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
af60: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
af70: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
af80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
af90: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
afa0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
afb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
afc0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
afd0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
afe0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
aff0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
b000: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
b010: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
b020: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
b030: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
b040: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
b050: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
b060: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
b070: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
b080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b090: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
b0a0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b0b0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
b0c0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
b0d0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b0e0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
b0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b100: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
b110: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
b120: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b130: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
b140: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
b150: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
b160: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
b170: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
b180: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
b190: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
b1a0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
b1b0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
b1c0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
b1d0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
b1e0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
b1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
b200: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
b210: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
b220: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
b230: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
b240: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
b250: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
b260: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
b270: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
b280: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
b290: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
b2a0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
b2b0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b2c0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
b2d0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
b2e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
b2f0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
b300: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
b310: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
b320: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
b330: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
b340: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
b350: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
b360: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
b370: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
b380: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
b390: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
b3a0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
b3b0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
b3c0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
b3d0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
b3e0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
b3f0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
b400: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
b410: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
b420: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
b430: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
b440: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
b450: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
b460: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
b470: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
b480: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
b490: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
b4a0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
b4b0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
b4c0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
b4d0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
b4e0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
b4f0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
b500: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
b510: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
b520: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
b530: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
b540: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
b550: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
b560: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
b570: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
b580: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
b590: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
b5a0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
b5b0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
b5c0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
b5d0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
b5e0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
b5f0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
b600: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
b610: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
b620: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
b630: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
b640: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
b650: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
b660: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
b670: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
b680: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
b690: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
b6a0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
b6b0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
b6c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
b6d0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
b6e0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
b6f0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
b700: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b710: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
b720: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
b730: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
b740: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
b750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
b760: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
b770: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
b780: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
b790: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
b7a0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
b7b0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
b7c0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
b7d0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
b7e0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
b7f0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
b800: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
b810: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
b820: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
b830: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
b840: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
b850: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
b860: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
b870: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
b880: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
b890: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
b8a0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
b8b0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
b8c0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
b8d0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
b8e0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
b8f0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
b900: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
b910: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
b920: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
b930: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
b940: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
b950: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
b960: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
b970: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
b980: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
b990: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
b9a0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
b9b0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
b9c0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
b9d0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
b9e0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
b9f0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
ba00: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
ba10: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
ba20: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
ba30: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
ba40: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
ba50: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
ba60: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
ba70: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
ba80: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
ba90: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
baa0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
bab0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
bac0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
bad0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
bae0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
baf0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
bb00: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
bb10: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
bb20: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
bb30: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
bb40: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
bb50: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
bb60: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
bb70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
bb80: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
bb90: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
bba0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
bbb0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
bbc0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
bbd0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
bbe0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
bbf0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
bc00: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
bc10: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
bc20: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
bc30: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
bc40: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
bc50: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
bc60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
bc70: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
bc80: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
bc90: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
bca0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
bcb0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
bcc0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
bcd0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
bce0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
bcf0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
bd00: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
bd10: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
bd20: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
bd30: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
bd40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
bd50: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
bd60: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
bd70: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
bd80: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
bd90: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
bda0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
bdb0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
bdc0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
bdd0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
bde0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
bdf0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
be00: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
be10: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
be20: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
be30: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
be40: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
be50: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
be60: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
be70: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
be80: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
be90: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
bea0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
beb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
bec0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
bed0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
bee0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
bef0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
bf00: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
bf10: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
bf20: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
bf30: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
bf40: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
bf50: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
bf60: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
bf70: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
bf80: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
bf90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
bfa0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
bfb0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
bfc0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
bfd0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
bfe0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
bff0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c000: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
c010: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
c020: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
c030: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
c040: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
c050: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
c060: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
c070: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
c080: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
c090: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
c0a0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
c0b0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c0c0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c0d0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
c0e0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
c0f0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
c100: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
c110: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
c120: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
c130: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
c140: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
c150: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
c160: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
c170: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
c180: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
c190: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
c1a0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
c1b0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
c1c0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
c1d0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
c1e0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
c1f0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c200: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
c210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
c220: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
c230: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
c240: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c250: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
c260: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
c270: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
c280: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
c290: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
c2a0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c2b0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
c2c0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
c2d0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
c2e0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
c2f0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
c300: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
c310: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
c320: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
c330: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
c340: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
c350: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
c360: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
c370: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
c380: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
c390: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
c3a0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
c3b0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
c3c0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
c3d0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
c3e0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
c3f0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
c400: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
c410: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
c420: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
c430: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
c440: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
c450: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
c460: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
c470: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
c480: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
c490: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
c4a0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
c4b0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
c4c0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
c4d0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
c4e0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
c4f0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
c500: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
c510: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
c520: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
c530: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
c540: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
c550: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
c560: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
c570: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
c580: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
c590: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
c5a0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
c5b0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
c5c0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
c5d0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
c5e0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
c5f0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
c600: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
c610: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
c620: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
c630: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
c640: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
c650: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
c660: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
c670: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
c680: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
c690: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
c6a0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
c6b0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
c6c0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
c6d0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
c6e0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
c6f0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
c700: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
c710: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
c720: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
c730: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
c740: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
c750: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
c760: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
c770: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
c780: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
c790: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
c7a0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
c7b0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
c7c0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
c7d0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
c7e0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
c7f0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
c800: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
c810: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
c820: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
c830: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
c840: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
c850: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
c860: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
c870: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
c880: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
c890: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
c8a0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
c8b0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
c8c0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
c8d0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
c8e0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
c8f0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
c900: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
c910: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
c920: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
c930: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
c940: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
c950: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
c960: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
c970: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
c980: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
c990: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
c9a0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
c9b0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
c9c0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
c9d0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
c9e0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
c9f0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
ca00: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
ca10: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
ca20: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
ca30: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
ca40: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
ca50: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
ca60: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
ca70: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
ca80: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
ca90: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
caa0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
cab0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
cac0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
cad0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
cae0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
caf0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
cb00: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
cb10: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
cb20: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
cb30: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
cb40: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
cb50: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
cb60: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
cb70: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
cb80: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
cb90: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
cba0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
cbb0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
cbc0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
cbd0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
cbe0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
cbf0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
cc00: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
cc10: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
cc20: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
cc30: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
cc40: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
cc50: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
cc60: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
cc70: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
cc80: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
cc90: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
cca0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
ccb0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
ccc0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
ccd0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
cce0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
ccf0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
cd00: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
cd10: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
cd20: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
cd30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
cd40: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
cd50: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
cd60: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
cd70: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
cd80: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
cd90: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
cda0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
cdb0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
cdc0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
cdd0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
cde0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
cdf0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
ce00: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
ce10: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
ce20: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
ce30: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
ce40: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
ce50: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
ce60: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
ce70: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
ce80: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
ce90: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
cea0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
ceb0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
cec0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
ced0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
cee0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
cef0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
cf00: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
cf10: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
cf20: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
cf30: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
cf40: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
cf50: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
cf60: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
cf70: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
cf80: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
cf90: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
cfa0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
cfb0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
cfc0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
cfd0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
cfe0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
cff0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
d000: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
d010: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
d020: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
d030: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
d040: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
d050: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
d060: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
d070: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
d080: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d090: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
d0a0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
d0b0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d0c0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d0d0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
d0e0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
d0f0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
d100: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
d110: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
d120: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
d130: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
d140: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
d150: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d160: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
d170: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
d180: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
d190: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
d1a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
d1b0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
d1c0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
d1d0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
d1e0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
d1f0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
d200: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
d210: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
d220: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
d230: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
d240: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
d250: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
d260: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
d270: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
d280: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
d290: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
d2a0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
d2b0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
d2c0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
d2d0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
d2e0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
d2f0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
d300: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
d310: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
d320: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
d330: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
d340: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
d350: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d360: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
d370: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
d380: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
d390: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
d3a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
d3b0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
d3c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d3d0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
d3e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
d3f0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
d400: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d410: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
d420: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
d430: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
d440: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
d450: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d460: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
d470: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
d480: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
d490: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d4a0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
d4b0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
d4c0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
d4d0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
d4e0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
d4f0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
d500: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
d510: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
d520: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
d530: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
d540: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
d550: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
d560: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
d570: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
d580: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
d590: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
d5a0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
d5b0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
d5c0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
d5d0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
d5e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d5f0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
d600: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
d610: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
d620: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
d630: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
d640: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
d650: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
d660: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
d670: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
d680: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
d690: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
d6a0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
d6b0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
d6c0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
d6d0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
d6e0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
d6f0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
d700: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
d710: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
d720: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
d730: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
d740: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
d750: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
d760: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
d770: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
d780: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
d790: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d7a0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d7b0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
d7c0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
d7d0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
d7e0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
d7f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d800: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
d810: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
d820: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
d830: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d840: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d850: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
d860: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
d870: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
d880: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
d890: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
d8a0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
d8b0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
d8c0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
d8d0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
d8e0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
d8f0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
d900: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
d910: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
d920: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
d930: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
d940: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
d950: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
d960: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
d970: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
d980: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
d990: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
d9a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
d9b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
d9c0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
d9d0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
d9e0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
d9f0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
da00: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
da10: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
da20: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
da30: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
da40: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
da50: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
da60: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
da70: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
da80: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
da90: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
daa0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
dab0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
dac0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
dad0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
dae0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
daf0: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
db00: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
db10: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
db20: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
db30: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
db40: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
db50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
db60: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
db70: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
db80: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
db90: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
dba0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
dbb0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
dbc0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
dbd0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
dbe0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
dbf0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
dc00: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
dc10: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
dc20: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
dc30: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
dc40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
dc50: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
dc60: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
dc70: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
dc80: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
dc90: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
dca0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
dcb0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
dcc0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
dcd0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
dce0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
dcf0: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
dd00: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
dd10: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
dd20: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
dd30: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
dd40: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
dd50: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
dd60: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
dd70: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
dd80: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
dd90: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
dda0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
ddb0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
ddc0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
ddd0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
dde0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
ddf0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
de00: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
de10: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
de20: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
de30: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
de40: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
de50: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
de60: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
de70: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
de80: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
de90: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
dea0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
deb0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
dec0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
ded0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
dee0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
def0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
df00: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
df10: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
df20: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
df30: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
df40: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
df50: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
df60: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
df70: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
df80: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
df90: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
dfa0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
dfb0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
dfc0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
dfd0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
dfe0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
dff0: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
e000: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
e010: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
e020: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
e030: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
e040: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
e050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e060: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
e070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e080: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
e090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e0a0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
e0b0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e0c0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e0d0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
e0e0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
e0f0: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
e100: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e110: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
e120: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
e130: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
e140: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
e150: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
e160: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
e170: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
e180: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
e190: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
e1a0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
e1b0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
e1c0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
e1d0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
e1e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
e1f0: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
e200: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
e210: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
e220: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
e230: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
e240: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
e250: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
e260: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
e270: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
e280: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
e290: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
e2a0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
e2b0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
e2c0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
e2d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
e2e0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
e2f0: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
e300: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
e310: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
e320: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
e330: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
e340: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
e350: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
e360: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
e370: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
e380: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
e390: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
e3a0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
e3b0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e3c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e3d0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
e3e0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
e3f0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
e400: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e410: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
e420: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
e430: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
e440: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
e450: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
e460: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e470: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
e480: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
e490: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e4a0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
e4b0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
e4c0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
e4d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e4e0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
e4f0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
e500: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
e510: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
e520: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
e530: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e540: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
e550: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
e560: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
e570: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
e580: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e590: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
e5a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e5b0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
e5c0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
e5d0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e5e0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
e5f0: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
e600: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
e610: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
e620: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e630: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
e640: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
e650: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e660: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
e670: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
e680: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
e690: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
e6a0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
e6b0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
e6c0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
e6d0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
e6e0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
e6f0: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
e700: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e710: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
e720: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
e730: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
e740: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
e750: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
e760: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
e770: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e780: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
e790: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
e7a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e7b0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
e7c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e7d0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
e7e0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
e7f0: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
e800: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
e810: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
e820: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e830: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
e840: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
e850: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
e860: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
e870: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
e880: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
e890: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
e8a0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
e8b0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
e8c0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
e8d0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
e8e0: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
e8f0: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
e900: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
e910: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
e920: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
e930: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e940: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e950: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
e960: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
e970: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
e980: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
e990: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
e9a0: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
e9b0: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
e9c0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
e9d0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
e9e0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
e9f0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
ea00: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
ea10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ea20: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
ea30: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
ea40: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
ea50: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
ea60: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
ea70: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
ea80: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
ea90: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
eaa0: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
eab0: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
eac0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
ead0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
eae0: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
eaf0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
eb00: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
eb10: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
eb20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
eb30: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
eb40: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
eb50: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
eb60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eb70: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
eb80: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
eb90: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
eba0: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
ebb0: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
ebc0: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
ebd0: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
ebe0: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
ebf0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
ec00: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
ec10: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
ec20: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
ec30: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
ec40: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
ec50: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
ec60: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
ec70: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
ec80: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
ec90: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
eca0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
ecb0: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
ecc0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
ecd0: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
ece0: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
ecf0: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
ed00: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
ed10: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
ed20: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
ed30: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
ed40: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
ed50: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
ed60: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
ed70: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
ed80: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
ed90: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
eda0: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
edb0: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
edc0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
edd0: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
ede0: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
edf0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
ee00: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
ee10: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
ee20: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
ee30: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
ee40: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
ee50: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
ee60: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
ee70: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
ee80: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
ee90: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
eea0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
eeb0: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
eec0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
eed0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
eee0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
eef0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
ef00: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ef10: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
ef20: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
ef30: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
ef40: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
ef50: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
ef60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
ef70: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ef80: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
ef90: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
efa0: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
efb0: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
efc0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
efd0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
efe0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
eff0: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
f000: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f010: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
f020: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f030: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
f040: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
f050: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f060: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
f070: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
f080: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
f090: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
f0a0: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
f0b0: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f0c0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f0d0: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
f0e0: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
f0f0: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
f100: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
f110: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
f120: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
f130: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
f140: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
f150: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f160: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
f170: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
f180: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
f190: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
f1a0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
f1b0: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
f1c0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f1d0: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
f1e0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f1f0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
f200: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
f210: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
f220: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
f230: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
f240: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
f250: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
f260: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
f270: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
f280: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
f290: 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
f2a0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
f2b0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
f2c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
f2d0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
f2e0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
f2f0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f300: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
f310: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
f320: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
f330: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
f340: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
f350: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
f360: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
f370: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
f380: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f390: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
f3a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
f3b0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
f3c0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
f3d0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
f3e0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
f3f0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
f400: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
f410: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
f420: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
f430: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
f440: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
f450: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f460: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
f470: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
f480: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
f490: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
f4a0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
f4b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
f4c0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
f4d0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
f4e0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
f4f0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
f500: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
f510: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f520: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
f530: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
f540: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
f550: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
f560: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
f570: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
f580: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
f590: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f5a0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
f5b0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
f5c0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
f5d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f5e0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
f5f0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
f600: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
f610: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
f620: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
f630: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
f640: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f650: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
f660: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
f670: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f680: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
f690: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
f6a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
f6b0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
f6c0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
f6d0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
f6e0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
f6f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f700: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
f710: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
f720: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
f730: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
f740: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
f750: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
f760: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
f770: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
f780: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
f790: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
f7a0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
f7b0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
f7c0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
f7d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f7e0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
f7f0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
f800: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
f810: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
f820: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
f830: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
f840: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
f850: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
f860: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
f870: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
f880: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
f890: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
f8a0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
f8b0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
f8c0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
f8d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
f8e0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
f8f0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
f900: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
f910: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
f920: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f930: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
f940: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
f950: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
f960: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
f970: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
f980: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
f990: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
f9a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
f9b0: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
f9c0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
f9d0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
f9e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
f9f0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
fa00: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
fa10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
fa20: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
fa30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
fa40: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
fa50: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
fa60: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
fa70: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
fa80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fa90: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
faa0: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
fab0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
fac0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
fad0: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
fae0: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
faf0: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
fb00: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
fb10: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
fb20: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
fb30: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
fb40: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
fb50: 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
fb60: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
fb70: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
fb80: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
fb90: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fba0: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
fbb0: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
fbc0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
fbd0: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
fbe0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
fbf0: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
fc00: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
fc10: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
fc20: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
fc30: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
fc40: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
fc50: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
fc60: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fc70: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
fc80: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
fc90: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
fca0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
fcb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
fcc0: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
fcd0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fce0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
fcf0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
fd00: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
fd10: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
fd20: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
fd30: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
fd40: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
fd50: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
fd60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fd70: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
fd80: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
fd90: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
fda0: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
fdb0: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
fdc0: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
fdd0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fde0: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
fdf0: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
fe00: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
fe10: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
fe20: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
fe30: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
fe40: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
fe50: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
fe60: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
fe70: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
fe80: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
fe90: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
fea0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
feb0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
fec0: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
fed0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
fee0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
fef0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
ff00: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
ff10: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
ff20: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
ff30: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
ff40: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
ff50: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
ff60: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
ff70: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
ff80: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
ff90: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
ffa0: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
ffb0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
ffc0: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
ffd0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
ffe0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
fff0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
10000 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
10010 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
10020 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
10030 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
10040 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
10050 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
10060 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
10070 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10080 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10090 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
100a0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
100b0 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
100c0 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
100d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
100e0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
100f0 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10100 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10110 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
10120 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
10130 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
10140 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10150 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
10160 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
10170 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
10180 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10190 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
101a0 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
101b0 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
101c0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
101d0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
101e0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
101f0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10200 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10210 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
10220 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
10230 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
10240 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10250 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
10260 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
10270 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
10280 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10290 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
102a0 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
102b0 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
102c0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
102d0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
102e0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
102f0 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
10300 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
10310 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
10320 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10330 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
10340 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
10350 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
10360 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
10370 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
10380 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10390 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
103a0 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
103b0 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
103c0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
103d0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
103e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
103f0 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
10400 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
10410 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
10420 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
10430 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
10440 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
10450 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
10460 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
10470 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
10480 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
10490 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
104a0 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
104b0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
104c0 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
104d0 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
104e0 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
104f0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
10500 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
10510 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
10520 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
10530 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
10540 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
10550 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
10560 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
10570 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
10580 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
10590 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
105a0 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
105b0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
105c0 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
105d0 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
105e0 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
105f0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
10600 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
10610 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
10620 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
10630 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
10640 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
10650 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
10660 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
10670 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10680 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
10690 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
106a0 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
106b0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
106c0 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
106d0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
106e0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
106f0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
10700 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
10710 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
10720 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
10730 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
10740 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
10750 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
10760 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
10770 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
10780 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
10790 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
107a0 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
107b0 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
107c0 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
107d0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
107e0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
107f0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
10800 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
10810 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
10820 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
10830 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
10840 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
10850 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
10860 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
10870 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
10880 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
10890 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
108a0 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
108b0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
108c0 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
108d0 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
108e0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
108f0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
10900 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
10910 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
10920 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
10930 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
10940 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
10950 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
10960 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
10970 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
10980 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
10990 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
109a0 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
109b0 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
109c0 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
109d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
109e0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
109f0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
10a00 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
10a10 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
10a20 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
10a30 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
10a40 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
10a50 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
10a60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
10a70 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
10a80 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
10a90 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
10aa0 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
10ab0 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
10ac0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10ad0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
10ae0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
10af0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
10b00 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
10b10 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10b20 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10b30 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10b40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10b50 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10b60 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
10b70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10b80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
10b90 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10ba0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10bb0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10bc0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
10bd0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
10be0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
10bf0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
10c00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10c10 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
10c20 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10c30 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10c40 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10c50 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10c60 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
10c70 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
10c80 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
10c90 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
10ca0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
10cb0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
10cc0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
10cd0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
10ce0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
10cf0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
10d00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10d10 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
10d20 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
10d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
10d40 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
10d50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
10d60 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
10d70 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10d80 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10d90 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10da0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
10db0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10dc0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
10dd0 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
10de0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
10df0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
10e00 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
10e10 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
10e20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
10e30 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
10e40 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
10e50 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
10e60 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10e70 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10e80 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10e90 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10ea0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10eb0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10ec0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
10ed0 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
10ee0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
10ef0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
10f00 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
10f10 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
10f20 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
10f30 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10f40 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
10f50 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
10f60 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
10f70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
10f80 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
10f90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
10fa0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
10fb0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10fc0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
10fd0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10fe0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
10ff0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
11000 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
11010 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
11020 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
11030 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
11040 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
11050 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
11060 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
11070 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
11080 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11090 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
110a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
110b0 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
110c0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
110d0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
110e0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
110f0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
11100 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
11110 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11120 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
11130 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
11140 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
11150 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
11160 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
11170 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
11180 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
11190 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
111a0 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
111b0 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
111c0 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
111d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
111e0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
111f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11200 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11210 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11220 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11230 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11240 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11250 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11260 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11270 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
11280 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
11290 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
112a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
112b0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
112c0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
112d0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
112e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
112f0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
11300 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
11310 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11320 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
11330 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
11340 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
11350 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
11360 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11370 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11380 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11390 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
113a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
113b0 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
113c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
113d0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
113e0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
113f0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
11400 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
11410 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
11420 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11430 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11440 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
11450 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
11460 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
11470 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
11480 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11490 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
114a0 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
114b0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
114c0 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
114d0 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
114e0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
114f0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11500 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11510 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
11520 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
11530 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
11540 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
11550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
11560 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
11570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11580 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
11590 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
115a0 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
115b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
115c0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
115d0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
115e0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
115f0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11600 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11610 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
11620 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
11630 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
11640 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11650 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
11660 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11670 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11680 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11690 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
116a0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
116b0 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
116c0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
116d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
116e0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
116f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11700 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
11710 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
11720 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
11730 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
11740 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11750 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
11760 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
11770 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
11780 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
11790 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
117a0 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
117b0 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
117c0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
117d0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
117e0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
117f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11800 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
11810 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
11820 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
11830 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
11840 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
11850 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
11860 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11870 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
11880 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
11890 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
118a0 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
118b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
118c0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
118d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
118e0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
118f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11900 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11910 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
11920 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
11930 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
11940 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
11950 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11960 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
11970 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
11980 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
11990 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
119a0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
119b0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
119c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
119d0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
119e0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
119f0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
11a00 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
11a10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
11a20 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
11a30 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
11a40 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
11a50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
11a60 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
11a70 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
11a80 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
11a90 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11aa0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11ab0 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
11ac0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11ad0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11ae0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11af0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11b00 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
11b10 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
11b20 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
11b30 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
11b40 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
11b50 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
11b60 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
11b70 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
11b80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11b90 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11ba0 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
11bb0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
11bc0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
11bd0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
11be0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
11bf0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
11c00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
11c10 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
11c20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
11c30 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
11c40 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
11c50 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
11c60 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
11c70 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
11c80 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
11c90 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
11ca0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11cb0 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
11cc0 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
11cd0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
11ce0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
11cf0 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
11d00 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
11d10 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
11d20 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
11d30 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
11d40 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
11d50 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11d60 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
11d70 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
11d80 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
11d90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11da0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
11db0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
11dc0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
11dd0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
11de0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
11df0 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
11e00 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
11e10 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
11e20 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
11e30 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
11e40 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
11e50 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
11e60 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
11e70 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
11e80 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
11e90 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
11ea0 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
11eb0 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
11ec0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
11ed0 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
11ee0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11ef0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
11f00 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
11f10 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11f20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
11f30 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
11f40 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
11f50 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
11f60 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
11f70 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
11f80 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
11f90 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
11fa0 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
11fb0 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
11fc0 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
11fd0 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
11fe0 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
11ff0 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
12000 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
12010 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
12020 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
12030 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
12040 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
12050 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
12060 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
12070 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12080 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12090 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
120a0 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
120b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
120c0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
120d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
120e0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
120f0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
12100 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
12110 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12120 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
12130 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12140 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
12150 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
12160 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12170 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12180 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12190 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
121a0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
121b0 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
121c0 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
121d0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
121e0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
121f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
12200 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
12210 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
12220 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
12230 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12240 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
12250 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
12260 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
12270 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
12280 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12290 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
122a0 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
122b0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
122c0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
122d0 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
122e0 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
122f0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
12300 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
12310 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
12320 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
12330 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
12340 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
12350 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
12360 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
12370 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
12380 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
12390 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
123a0 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
123b0 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
123c0 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
123d0 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
123e0 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
123f0 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
12400 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
12410 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
12420 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
12430 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
12440 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
12450 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
12460 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
12470 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
12480 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12490 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
124a0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
124b0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
124c0 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
124d0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
124e0 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
124f0 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
12500 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
12510 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
12520 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
12530 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
12540 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
12550 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
12560 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
12570 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
12580 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
12590 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
125a0 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
125b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
125c0 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
125d0 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
125e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
125f0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
12600 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
12610 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
12620 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
12630 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
12640 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
12650 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12660 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
12670 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12680 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
12690 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
126a0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
126b0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
126c0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
126d0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
126e0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
126f0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
12700 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
12710 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
12720 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
12730 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12740 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
12750 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
12760 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
12770 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
12780 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
12790 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
127a0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
127b0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
127c0 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
127d0 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
127e0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
127f0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
12800 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
12810 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
12820 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
12830 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
12840 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
12850 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
12860 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
12870 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
12880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
12890 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
128a0 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
128b0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
128c0 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
128d0 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
128e0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
128f0 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
12900 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
12910 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
12920 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
12930 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
12940 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
12950 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
12960 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
12970 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
12980 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
12990 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
129a0 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
129b0 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
129c0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
129d0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
129e0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
129f0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
12a00 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
12a10 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
12a20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
12a30 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
12a40 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
12a50 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
12a60 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
12a70 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
12a80 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12a90 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
12aa0 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
12ab0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12ac0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
12ad0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12ae0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
12af0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12b00 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12b10 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12b20 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12b30 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12b40 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12b50 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12b60 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
12b70 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
12b80 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
12b90 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
12ba0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12bb0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
12bc0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
12bd0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
12be0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
12bf0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
12c00 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
12c10 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12c20 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
12c30 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
12c40 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
12c50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12c60 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
12c70 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12c80 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12c90 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12ca0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12cb0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12cc0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12cd0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
12ce0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
12cf0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
12d00 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
12d10 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
12d20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12d30 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
12d40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
12d50 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
12d60 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
12d70 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12d80 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
12d90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12da0 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
12db0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12dc0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
12dd0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12de0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12df0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12e00 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12e10 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12e20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12e30 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12e40 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
12e50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
12e60 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12e70 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12e80 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12e90 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
12ea0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
12eb0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
12ec0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
12ed0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
12ee0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
12ef0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
12f00 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
12f10 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
12f20 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
12f30 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
12f40 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
12f50 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
12f60 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12f70 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12f80 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12f90 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12fa0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12fb0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12fc0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
12fd0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
12fe0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
12ff0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
13000 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
13010 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
13020 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
13030 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13040 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
13050 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
13060 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
13070 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13080 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13090 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
130a0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
130b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
130c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
130d0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
130e0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
130f0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
13100 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
13110 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13120 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
13130 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13140 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
13150 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13160 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
13170 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
13180 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
13190 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
131a0 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
131b0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
131c0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
131d0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
131e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
131f0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
13200 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
13210 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
13220 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
13230 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
13240 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13250 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
13260 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
13270 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
13280 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
13290 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
132a0 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
132b0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
132c0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
132d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
132e0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
132f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13300 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
13310 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13320 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13330 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13340 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
13350 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
13360 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
13370 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
13380 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
13390 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
133a0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
133b0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
133c0 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
133d0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
133e0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
133f0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
13400 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
13410 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
13420 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13430 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13440 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
13450 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
13460 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13470 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13480 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13490 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
134a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
134b0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
134c0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
134d0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
134e0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
134f0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
13500 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
13510 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
13520 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13530 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13540 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13550 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
13560 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
13570 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
13580 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
13590 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
135a0 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
135b0 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
135c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
135d0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
135e0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
135f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
13600 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
13610 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
13620 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
13630 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
13640 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
13650 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
13660 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
13670 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13680 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
13690 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
136a0 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
136b0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
136c0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
136d0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
136e0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
136f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
13700 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
13710 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
13720 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
13730 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
13740 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
13750 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
13760 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
13770 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
13780 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
13790 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
137a0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
137b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
137c0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
137d0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
137e0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
137f0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
13800 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
13810 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
13820 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
13830 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
13840 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
13850 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
13860 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
13870 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
13880 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
13890 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
138a0 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
138b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
138c0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
138d0 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
138e0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
138f0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
13900 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
13910 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
13920 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
13930 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
13940 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
13950 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
13960 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
13970 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
13980 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
13990 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
139a0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
139b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
139c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
139d0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
139e0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
139f0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
13a00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13a10 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
13a20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13a30 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  _URI.** <dd> Thi
13a40 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13a50 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13a60 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
13a70 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
13a80 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
13a90 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
13aa0 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
13ab0 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
13ac0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
13ad0 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
13ae0 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49  disabled. If URI
13af0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13b00 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
13b10 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
13b20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
13b30 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
13b40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
13b50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
13b60 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
13b70 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
13b80 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
13b90 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
13ba0 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
13bb0 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
13bc0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
13bd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
13be0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
13bf0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
13c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
13c10 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20  pened. If it is 
13c20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
13c30 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
13c40 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
13c50 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
13c60 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
13c70 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
13c80 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
13c90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
13ca0 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65  is opened. By de
13cb0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
13cc0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
13cd0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
13ce0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
13cf0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
13d00 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
13d10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
13d20 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
13d30 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efined..**.** [[
13d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
13d50 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
13d60 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
13d70 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
13d80 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
13d90 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
13da0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
13db0 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68  eger argument wh
13dc0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
13dd0 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ed as.** a boole
13de0 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
13df0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
13e00 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
13e10 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
13e20 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  .** full table s
13e30 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
13e40 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68  y optimizer.  Th
13e50 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
13e60 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
13e70 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
13e80 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
13e90 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
13ea0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13eb0 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
13ec0 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
13ed0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
13ee0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
13ef0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
13f00 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
13f10 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
13f20 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
13f30 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
13f40 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
13f50 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
13f60 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
13f70 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
13f80 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65   malfunction whe
13f90 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
13fa0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
13fb0 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
13fc0 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
13fd0 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
13fe0 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
13ff0 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
14000 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
14010 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
14020 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
14030 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
14040 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
14050 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14060 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
14070 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14080 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
14090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
140a0 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
140b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
140c0 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
140d0 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
140e0 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
140f0 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
14100 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
14110 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
14120 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
14130 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
14140 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
14150 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14160 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14170 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14180 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
14190 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
141a0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
141b0 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
141c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
141d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
141e0 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
141f0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
14200 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
14210 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
14220 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
14230 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
14240 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
14250 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
14260 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
14270 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
14280 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
14290 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
142a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
142b0 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
142c0 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
142d0 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
142e0 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
142f0 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
14300 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
14310 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14320 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
14330 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
14340 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
14350 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
14360 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
14370 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
14380 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
14390 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
143a0 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
143b0 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
143c0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
143d0 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
143e0 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
143f0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
14400 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
14410 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
14420 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
14430 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
14440 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
14450 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
14460 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
14470 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14480 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
14490 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
144a0 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
144b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
144c0 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
144d0 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
144e0 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
144f0 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
14500 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
14510 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
14520 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
14530 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
14540 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
14550 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
14560 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
14570 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
14580 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
14590 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
145a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
145b0 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
145c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
145d0 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c 49  SIZE.** <dd>SQLI
145e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
145f0 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
14600 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
14610 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
14620 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
14630 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
14640 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
14650 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
14660 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
14670 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
14680 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
14690 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
146a0 6d 69 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  mit..** The defa
146b0 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
146c0 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
146d0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
146e0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
146f0 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
14700 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
14710 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
14720 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
14730 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
14740 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
14750 6f 6c 2e 20 20 54 68 65 20 6d 61 78 69 6d 75 6d  ol.  The maximum
14760 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
14770 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
14780 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
14790 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
147a0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
147b0 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
147c0 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
147d0 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
147e0 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
147f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
14800 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
14810 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14820 6e 2e 20 20 0a 2a 2a 20 49 66 20 65 69 74 68 65  n.  .** If eithe
14830 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
14840 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
14850 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
14860 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
14870 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
14880 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
14890 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ult..** </dl>.*/
148a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
148b0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
148c0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
148d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
148e0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
148f0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
14900 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14910 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
14920 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
14930 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14940 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
14950 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
14960 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14970 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
14980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14990 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
149a0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
149b0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
149c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
149d0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
149e0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
149f0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
14a00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14a10 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
14a20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
14a30 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
14a40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14a50 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
14a60 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
14a70 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
14a80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14a90 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14aa0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
14ab0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
14ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14ad0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
14ae0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
14af0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
14b00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14b10 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
14b20 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
14b30 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
14b40 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
14b50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
14b60 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
14b70 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
14b80 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
14b90 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14ba0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
14bb0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14bd0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
14be0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
14bf0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14c00 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
14c10 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
14c20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14c30 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
14c40 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
14c50 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
14c60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14c70 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
14c80 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
14c90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14ca0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
14cb0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
14cc0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
14cd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14ce0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
14cf0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
14d00 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14d10 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14d20 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14d30 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
14d40 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
14d50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14d60 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
14d70 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
14d80 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
14d90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14da0 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
14db0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
14dc0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
14dd0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
14de0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
14df0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
14e00 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
14e10 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
14e20 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
14e30 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
14e40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14e50 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
14e60 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
14e70 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14e80 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
14e90 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
14ea0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
14eb0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
14ec0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
14ed0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
14ee0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
14ef0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
14f00 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14f10 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
14f20 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
14f30 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
14f40 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
14f50 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
14f60 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14f70 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
14f80 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
14f90 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
14fa0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
14fb0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
14fc0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
14fd0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
14fe0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
14ff0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
15000 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
15010 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
15020 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
15030 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
15040 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15050 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
15060 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
15070 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
15080 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
15090 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
150a0 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
150b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
150c0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
150d0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
150e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
150f0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
15100 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
15110 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15120 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
15130 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
15140 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
15150 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
15160 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
15170 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
15180 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15190 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
151a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
151b0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
151c0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
151d0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
151e0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
151f0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
15200 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
15210 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
15220 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
15230 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
15240 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
15250 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
15260 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
15270 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
15280 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15290 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
152a0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
152b0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
152c0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
152d0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
152e0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
152f0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
15300 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
15310 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
15320 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
15330 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15340 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
15350 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
15360 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
15370 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15380 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
15390 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
153a0 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
153b0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
153c0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
153d0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
153e0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
153f0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
15400 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
15410 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
15420 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
15430 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
15440 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
15450 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
15460 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
15470 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
15480 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
15490 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
154a0 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
154b0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
154c0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
154d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
154e0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
154f0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
15500 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
15510 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
15520 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
15530 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
15540 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
15550 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
15560 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
15570 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
15580 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
15590 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
155a0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
155b0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
155c0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
155d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
155e0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
155f0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
15600 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
15610 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
15620 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
15630 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
15640 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
15650 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
15660 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
15670 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
15680 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
15690 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
156a0 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
156b0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
156c0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
156d0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
156e0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
156f0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
15700 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15710 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15720 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
15730 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
15740 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
15750 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
15760 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
15770 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
15780 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
15790 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
157a0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
157b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
157c0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
157d0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
157e0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
157f0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
15800 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
15810 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
15820 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
15830 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15840 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
15850 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
15860 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
15870 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
15880 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
15890 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
158a0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
158b0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
158c0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
158d0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
158e0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
158f0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
15900 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
15910 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
15920 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
15930 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
15940 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
15950 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
15960 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15970 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
15980 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
15990 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
159a0 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
159b0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
159c0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
159d0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
159e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
159f0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
15a00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
15a10 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
15a20 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
15a30 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
15a40 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
15a50 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
15a60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
15a70 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15a80 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
15a90 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
15aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15ab0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
15ac0 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
15ad0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
15ae0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15af0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
15b00 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
15b10 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
15b20 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
15b30 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
15b40 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
15b50 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
15b60 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
15b70 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
15b80 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
15b90 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
15ba0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
15bb0 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
15bc0 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
15bd0 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
15be0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
15bf0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
15c00 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
15c10 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
15c20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
15c30 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
15c40 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
15c50 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
15c60 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
15c70 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
15c80 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
15c90 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61  ^Each entry in a
15ca0 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68  n SQLite table h
15cb0 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
15cc0 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
15cd0 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
15ce0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
15cf0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
15d00 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
15d10 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
15d20 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
15d30 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
15d40 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
15d50 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
15d60 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
15d70 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
15d80 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
15d90 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
15da0 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
15db0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
15dc0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
15dd0 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
15de0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
15df0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
15e00 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
15e10 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
15e20 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
15e30 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  ] of the most re
15e40 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
15e50 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
15e60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
15e70 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
15e80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
15e90 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
15ea0 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53  ument.  ^As of S
15eb0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
15ec0 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  7.7, this routin
15ed0 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68  es.** records th
15ee0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
15ef0 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69  wid of both ordi
15f00 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20  nary tables and 
15f10 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
15f20 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
15f30 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
15f40 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
15f50 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
15f60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15f70 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
15f80 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  rned..**.** ^(If
15f90 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
15fa0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
15fb0 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
15fc0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
15fd0 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
15fe0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
15ff0 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
16000 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
16010 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
16020 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
16030 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
16040 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
16050 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
16060 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
16070 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
16080 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
16090 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
160a0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
160b0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
160c0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
160d0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
160e0 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
160f0 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
16100 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
16110 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
16120 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
16130 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
16140 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
16150 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
16160 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
16170 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
16180 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
16190 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
161a0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
161b0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
161c0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
161d0 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
161e0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
161f0 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
16200 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
16210 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
16220 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
16230 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
16240 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
16250 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
16260 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
16270 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
16280 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
16290 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
162a0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
162b0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
162c0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
162d0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
162e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
162f0 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
16300 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
16310 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
16320 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
16330 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
16340 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
16350 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
16360 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
16370 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
16380 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
16390 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
163a0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
163b0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
163c0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
163d0 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
163e0 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
163f0 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
16400 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
16410 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
16420 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
16430 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
16440 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
16450 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
16460 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
16470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
16480 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
16490 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
164a0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
164b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
164c0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
164d0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
164e0 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
164f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
16500 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
16510 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
16520 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
16530 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
16540 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
16550 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
16560 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
16570 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
16580 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
16590 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
165a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
165b0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
165c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
165d0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
165e0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
165f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
16600 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
16610 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
16620 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
16630 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
16640 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
16650 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
16660 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
16670 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
16680 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
16690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
166a0 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
166b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
166c0 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
166d0 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
166e0 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
166f0 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
16700 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
16710 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
16720 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
16730 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
16740 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
16750 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
16760 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
16770 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
16780 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
16790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
167a0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
167b0 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
167c0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
167d0 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
167e0 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
167f0 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
16800 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
16810 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
16820 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
16830 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
16840 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
16850 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
16860 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
16870 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
16880 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
16890 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
168a0 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
168b0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
168c0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
168d0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
168e0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
168f0 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
16900 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
16910 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
16920 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
16930 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
16940 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
16950 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
16960 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
16970 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
16980 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
16990 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
169a0 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
169b0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
169c0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
169d0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
169e0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
169f0 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
16a00 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
16a10 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
16a20 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
16a30 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
16a40 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
16a50 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
16a60 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
16a70 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
16a80 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
16a90 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
16aa0 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
16ab0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
16ac0 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
16ad0 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
16ae0 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
16af0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
16b00 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
16b10 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
16b20 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
16b30 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
16b40 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
16b50 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
16b60 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
16b70 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
16b80 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
16b90 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
16ba0 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
16bb0 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
16bc0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
16bd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
16be0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
16bf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
16c00 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
16c10 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
16c20 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
16c30 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
16c40 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
16c50 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
16c60 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
16c70 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
16c80 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
16c90 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
16ca0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
16cb0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
16cc0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
16cd0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
16ce0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
16cf0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
16d00 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
16d10 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
16d20 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
16d30 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
16d40 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
16d50 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
16d60 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
16d70 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
16d80 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
16d90 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
16da0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
16db0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
16dc0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
16dd0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
16de0 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
16df0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
16e00 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
16e10 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
16e20 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
16e30 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
16e40 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
16e50 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
16e60 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
16e70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
16e80 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
16e90 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
16ea0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
16eb0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
16ec0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
16ed0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
16ee0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
16ef0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
16f00 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
16f10 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
16f20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
16f30 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
16f40 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
16f50 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
16f60 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
16f70 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
16f80 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
16f90 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
16fa0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
16fb0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
16fc0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
16fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
16fe0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
16ff0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
17000 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
17010 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
17020 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
17030 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
17040 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
17050 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
17060 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
17070 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
17080 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
17090 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
170a0 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
170b0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
170c0 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
170d0 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
170e0 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
170f0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17100 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
17110 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
17120 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
17130 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
17140 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
17150 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17160 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
17170 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
17180 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
17190 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
171a0 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
171b0 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
171c0 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
171d0 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
171e0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
171f0 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
17200 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
17210 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
17220 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
17230 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
17240 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
17250 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
17260 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
17270 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
17280 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
17290 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
172a0 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
172b0 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
172c0 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
172d0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
172e0 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
172f0 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
17300 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
17310 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
17320 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
17330 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17340 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
17350 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
17360 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
17370 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17380 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17390 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
173a0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
173b0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
173c0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
173d0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
173e0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
173f0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
17400 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
17410 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
17420 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17430 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
17440 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
17450 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
17460 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
17470 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
17480 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
17490 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
174a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
174b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
174c0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
174d0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
174e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
174f0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
17500 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
17510 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
17520 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
17530 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
17540 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
17550 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
17560 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
17570 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
17580 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
17590 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
175a0 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
175b0 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
175c0 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
175d0 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
175e0 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
175f0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
17600 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
17610 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
17620 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
17630 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
17640 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
17650 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
17660 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
17670 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
17680 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
17690 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
176a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
176b0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
176c0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
176d0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
176e0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
176f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17700 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
17710 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
17720 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
17730 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
17740 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
17750 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
17760 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
17770 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
17780 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
17790 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
177a0 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
177b0 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
177c0 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
177d0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
177e0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
177f0 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
17800 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
17810 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
17820 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
17830 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
17840 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
17850 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
17860 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
17870 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
17880 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
17890 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
178a0 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
178b0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
178c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
178d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
178e0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
178f0 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
17900 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
17910 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
17920 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
17930 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
17940 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
17950 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
17960 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
17970 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
17980 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
17990 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
179a0 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
179b0 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
179c0 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
179d0 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
179e0 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
179f0 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
17a00 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
17a10 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17a20 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
17a30 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
17a40 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
17a50 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
17a60 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
17a70 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
17a80 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
17a90 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
17aa0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17ab0 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
17ac0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
17ad0 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
17ae0 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
17af0 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
17b00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17b10 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
17b20 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
17b30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
17b40 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
17b50 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
17b60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17b70 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
17b80 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
17b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17ba0 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
17bb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17bc0 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
17bd0 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
17be0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
17bf0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
17c00 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
17c10 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
17c20 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17c30 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
17c40 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
17c50 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
17c60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
17c70 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
17c80 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
17c90 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
17ca0 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
17cb0 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
17cc0 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
17cd0 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
17ce0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
17cf0 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
17d00 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
17d10 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
17d20 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
17d30 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
17d40 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
17d50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
17d60 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
17d70 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
17d80 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
17d90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
17da0 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
17db0 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
17dc0 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
17dd0 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
17de0 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
17df0 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
17e00 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
17e10 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
17e20 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
17e30 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
17e40 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
17e50 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
17e60 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
17e70 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
17e80 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
17e90 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
17ea0 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
17eb0 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
17ec0 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
17ed0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
17ee0 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
17ef0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
17f00 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
17f10 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
17f20 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
17f30 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
17f40 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
17f50 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
17f60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
17f70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
17f80 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
17f90 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
17fa0 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
17fb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
17fc0 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
17fd0 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
17fe0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
17ff0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
18000 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
18010 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
18020 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
18030 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
18040 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
18050 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
18060 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
18070 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
18080 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
18090 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
180a0 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
180b0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
180c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
180d0 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
180e0 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
180f0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
18100 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
18110 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
18120 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
18130 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
18140 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
18150 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18160 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
18170 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
18180 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
18190 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
181a0 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
181b0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
181c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
181d0 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
181e0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
181f0 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
18200 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
18210 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
18220 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
18230 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
18240 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
18250 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
18260 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
18270 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
18280 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18290 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
182a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
182b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
182c0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
182d0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
182e0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
182f0 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
18300 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
18310 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
18320 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
18330 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
18340 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
18350 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
18360 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
18370 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
18380 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
18390 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
183a0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
183b0 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
183c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
183d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
183e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
183f0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
18400 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
18410 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
18420 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
18430 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
18440 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
18450 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
18460 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
18470 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
18480 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
18490 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
184a0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
184b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
184c0 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
184d0 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
184e0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
184f0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
18500 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
18510 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
18520 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
18530 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
18540 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
18550 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
18560 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
18570 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
18580 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
18590 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
185a0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
185b0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
185c0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
185d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
185e0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
185f0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
18600 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
18610 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
18620 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
18630 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
18640 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
18650 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
18660 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
18670 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
18680 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
18690 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
186a0 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
186b0 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
186c0 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
186d0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
186e0 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
186f0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
18700 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
18710 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
18720 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
18730 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
18740 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
18750 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
18760 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
18770 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
18780 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
18790 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
187a0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
187b0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
187c0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
187d0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
187e0 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
187f0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
18800 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
18810 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
18820 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
18830 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
18840 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
18850 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
18860 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
18870 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
18880 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
18890 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
188a0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
188b0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
188c0 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
188d0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
188e0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
188f0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
18900 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
18910 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
18920 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
18930 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
18940 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
18950 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
18960 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
18970 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
18980 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
18990 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
189a0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
189b0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
189c0 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
189d0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
189e0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
189f0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
18a00 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
18a10 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
18a20 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
18a30 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
18a40 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
18a50 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
18a60 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
18a70 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
18a80 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
18a90 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
18aa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
18ab0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
18ac0 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
18ad0 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
18ae0 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
18af0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
18b00 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
18b10 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
18b20 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
18b30 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
18b40 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
18b50 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
18b60 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
18b70 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
18b80 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
18b90 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
18ba0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
18bb0 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
18bc0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
18bd0 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
18be0 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
18bf0 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
18c00 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
18c10 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
18c20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
18c30 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
18c40 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
18c50 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
18c60 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
18c70 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
18c80 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
18c90 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
18ca0 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
18cb0 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
18cc0 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
18cd0 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
18ce0 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
18cf0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
18d00 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
18d10 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
18d20 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
18d30 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
18d40 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
18d50 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
18d60 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
18d70 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
18d80 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
18d90 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
18da0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
18db0 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
18dc0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
18dd0 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
18de0 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
18df0 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
18e00 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
18e10 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
18e20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
18e30 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
18e40 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
18e50 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
18e60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18e70 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
18e80 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
18e90 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
18ea0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
18eb0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
18ec0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
18ed0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
18ee0 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
18ef0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
18f00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
18f10 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
18f20 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
18f30 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
18f40 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
18f50 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
18f60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
18f70 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
18f80 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
18f90 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
18fa0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
18fb0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
18fc0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
18fd0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
18fe0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
18ff0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
19000 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
19010 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
19020 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
19030 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
19040 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
19050 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
19060 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
19070 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
19080 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19090 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
190a0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
190b0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
190c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
190d0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
190e0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
190f0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
19100 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
19110 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
19120 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
19130 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
19140 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
19150 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
19160 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
19170 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
19180 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
19190 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
191a0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
191b0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
191c0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
191d0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
191e0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
191f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19200 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
19210 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
19220 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
19230 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
19240 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
19250 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
19260 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
19270 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
19280 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
19290 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
192a0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
192b0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
192c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
192d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
192e0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
192f0 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
19300 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
19310 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
19320 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
19330 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
19340 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19350 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
19360 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
19370 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
19380 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
19390 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
193a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
193b0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
193c0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
193d0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
193e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
193f0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
19400 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
19410 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
19420 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
19430 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
19440 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
19450 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
19460 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
19470 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
19480 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
19490 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
194a0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
194b0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
194c0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
194d0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
194e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
194f0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
19500 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
19510 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
19520 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
19530 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
19540 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
19550 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
19560 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
19570 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
19580 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
19590 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
195a0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
195b0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
195c0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
195d0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
195e0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
195f0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
19600 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
19610 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
19620 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
19630 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
19640 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
19650 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
19660 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
19670 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
19680 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
19690 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
196a0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
196b0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
196c0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
196d0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
196e0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
196f0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
19700 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
19710 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
19720 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
19730 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
19740 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
19750 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
19760 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
19770 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
19780 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
19790 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
197a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
197b0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
197c0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
197d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
197e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
197f0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
19800 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
19810 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
19820 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
19830 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
19840 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
19850 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
19860 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
19870 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
19880 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
19890 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
198a0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
198b0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
198c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
198d0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
198e0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
198f0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
19900 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
19910 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
19920 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
19930 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
19940 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
19950 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
19960 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19970 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
19980 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
19990 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
199a0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
199b0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
199c0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
199d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
199e0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
199f0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
19a00 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
19a10 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
19a20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
19a30 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
19a40 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
19a50 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
19a60 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
19a70 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
19a80 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
19a90 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
19aa0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
19ab0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
19ac0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19ad0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
19ae0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19af0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
19b00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19b10 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
19b20 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
19b30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
19b40 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
19b50 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19b60 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
19b70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19b80 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
19b90 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19ba0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
19bb0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19bc0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
19bd0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
19be0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
19bf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
19c00 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
19c10 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
19c20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
19c30 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
19c40 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
19c50 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
19c60 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
19c70 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
19c80 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
19c90 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
19ca0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
19cb0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
19cc0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
19cd0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
19ce0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
19cf0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
19d00 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
19d10 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
19d20 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
19d30 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
19d40 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
19d50 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
19d60 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
19d70 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
19d80 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
19d90 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
19da0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
19db0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
19dc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
19dd0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
19de0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19df0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
19e00 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
19e10 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
19e20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
19e30 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
19e40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
19e50 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
19e60 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
19e70 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
19e80 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
19e90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
19ea0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
19eb0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
19ec0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
19ed0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
19ee0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
19ef0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
19f00 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
19f10 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
19f20 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
19f30 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
19f40 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
19f50 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
19f60 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
19f70 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
19f80 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
19f90 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
19fa0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
19fb0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
19fc0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
19fd0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
19fe0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
19ff0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1a000 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1a010 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1a020 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1a030 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1a040 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1a050 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1a060 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1a070 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1a080 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1a090 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1a0a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1a0b0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1a0c0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1a0d0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1a0e0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1a0f0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1a100 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1a110 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1a120 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1a130 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1a140 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1a150 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1a160 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1a170 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1a180 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1a190 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1a1a0 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1a1b0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1a1c0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1a1d0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1a1e0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1a1f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a200 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1a210 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1a220 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1a230 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1a240 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1a250 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1a260 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1a270 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1a280 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1a290 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1a2a0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1a2b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1a2c0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1a2d0 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1a2e0 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1a2f0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1a300 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a310 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1a320 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1a330 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1a340 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1a350 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1a360 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1a370 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1a380 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1a390 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1a3a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1a3b0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1a3c0 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1a3d0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1a3e0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1a3f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1a400 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1a410 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1a420 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1a430 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1a440 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1a450 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1a460 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1a470 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1a480 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1a490 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1a4a0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1a4b0 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1a4c0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1a4d0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1a4e0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1a4f0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1a500 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1a510 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1a520 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1a530 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1a540 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1a550 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1a560 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1a570 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1a580 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1a590 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1a5a0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1a5b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1a5c0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1a5d0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1a5e0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1a5f0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1a600 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1a610 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1a620 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1a630 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1a640 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1a650 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1a660 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1a670 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1a680 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1a690 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1a6a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1a6b0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1a6c0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1a6d0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1a6e0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1a6f0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1a700 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1a710 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1a720 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1a730 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1a740 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1a750 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1a760 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1a770 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1a780 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1a790 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1a7a0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1a7b0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1a7c0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1a7d0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1a7e0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1a7f0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1a800 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1a810 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1a820 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1a830 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1a840 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1a850 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1a860 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1a870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1a880 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1a890 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1a8a0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1a8b0 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1a8c0 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1a8d0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1a8e0 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1a8f0 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1a900 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1a910 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1a920 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1a930 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1a940 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
1a950 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1a960 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1a970 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1a980 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1a990 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1a9a0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1a9b0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1a9c0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1a9d0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1a9e0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1a9f0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1aa00 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1aa10 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1aa20 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1aa30 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1aa40 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1aa50 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1aa60 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1aa70 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1aa80 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1aa90 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1aaa0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1aab0 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1aac0 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1aad0 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1aae0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1aaf0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1ab00 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1ab10 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1ab20 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1ab30 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1ab40 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1ab50 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1ab60 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1ab70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1ab80 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1ab90 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1aba0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1abb0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1abc0 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1abd0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1abe0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1abf0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1ac00 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1ac10 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1ac20 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1ac30 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1ac40 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1ac50 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1ac60 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1ac70 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1ac80 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1ac90 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1aca0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1acb0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1acc0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1acd0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1ace0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1acf0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1ad00 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1ad10 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1ad20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1ad30 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1ad40 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1ad50 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1ad60 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1ad70 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1ad80 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1ad90 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1ada0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1adb0 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1adc0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1add0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1ade0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1adf0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1ae00 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1ae10 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1ae20 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1ae30 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1ae40 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1ae50 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1ae60 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1ae70 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1ae80 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1ae90 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1aea0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1aeb0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1aec0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1aed0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1aee0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1aef0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1af00 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1af10 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1af20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1af30 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1af40 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1af50 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1af60 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1af70 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1af80 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1af90 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1afa0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1afb0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1afc0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1afd0 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1afe0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1aff0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1b000 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1b010 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1b020 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1b030 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b040 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1b050 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1b060 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1b070 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1b080 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1b090 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1b0a0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1b0b0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1b0c0 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1b0d0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1b0e0 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1b0f0 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1b100 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1b110 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1b120 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1b130 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1b140 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1b150 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1b160 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1b170 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53  t string.)^.*/.S
1b180 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1b190 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b1a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1b1b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1b1c0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1b1d0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1b1e0 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54   va_list);.SQLIT
1b1f0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1b200 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1b210 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1b220 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  r*, ...);.SQLITE
1b230 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1b240 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1b250 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1b260 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1b270 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1b280 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1b290 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1b2a0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1b2b0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1b2c0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1b2d0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1b2e0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1b2f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1b300 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1b310 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1b320 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1b330 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1b340 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1b350 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1b360 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1b370 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1b380 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1b390 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1b3a0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1b3b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b3c0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1b3d0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1b3e0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1b3f0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1b400 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1b410 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1b420 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1b430 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1b440 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1b450 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1b460 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1b470 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1b480 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1b490 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1b4a0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1b4b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b4c0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1b4d0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1b4e0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1b4f0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1b500 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
1b510 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1b520 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1b530 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1b540 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1b550 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1b560 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b570 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1b580 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1b590 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1b5a0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1b5b0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1b5c0 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1b5d0 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1b5e0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1b5f0 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1b600 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1b610 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1b620 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1b630 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1b640 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1b650 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1b660 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1b670 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1b680 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1b690 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1b6a0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1b6b0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1b6c0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1b6d0 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1b6e0 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1b6f0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1b700 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1b710 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1b720 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1b730 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1b740 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1b750 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1b760 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1b770 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1b780 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1b790 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1b7a0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1b7b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
1b7c0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1b7d0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1b7e0 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1b7f0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
1b800 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
1b810 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1b820 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b830 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
1b840 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1b850 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
1b860 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1b870 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
1b880 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1b890 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b8a0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
1b8b0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1b8c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1b8d0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1b8e0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1b8f0 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
1b900 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1b910 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1b920 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1b930 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
1b940 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b950 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
1b960 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1b970 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1b980 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1b990 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1b9a0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1b9b0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
1b9c0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
1b9d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1b9e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1b9f0 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1ba00 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1ba10 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1ba20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1ba30 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1ba40 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1ba50 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1ba60 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1ba70 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1ba80 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1ba90 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1baa0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1bab0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1bac0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1bad0 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1bae0 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1baf0 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1bb00 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1bb10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1bb20 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1bb30 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1bb40 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1bb50 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1bb60 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1bb70 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1bb80 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1bb90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1bba0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1bbb0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1bbc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1bbd0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1bbe0 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1bbf0 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1bc00 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1bc10 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1bc20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1bc30 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1bc40 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1bc50 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1bc60 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1bc70 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1bc80 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1bc90 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1bca0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1bcb0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1bcc0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1bcd0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1bce0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1bcf0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1bd00 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1bd10 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1bd20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1bd30 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1bd40 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1bd50 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1bd60 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1bd70 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1bd80 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1bd90 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1bda0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1bdb0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1bdc0 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1bdd0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1bde0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1bdf0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1be00 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1be10 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1be20 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1be30 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1be40 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1be50 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1be60 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1be70 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1be80 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1be90 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1bea0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1beb0 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1bec0 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1bed0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1bee0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1bef0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1bf00 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1bf10 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1bf20 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1bf30 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1bf40 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1bf50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1bf60 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1bf70 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1bf80 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1bf90 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1bfa0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1bfb0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1bfc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1bfd0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1bfe0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1bff0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1c000 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1c010 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1c020 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1c030 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1c040 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1c050 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1c060 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1c070 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1c080 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1c090 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c0a0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1c0b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d   void *sqlite3_m
1c0c0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49  alloc(int);.SQLI
1c0d0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1c0e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1c0f0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
1c100 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1c110 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
1c120 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c130 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1c140 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1c150 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1c160 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1c170 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1c180 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1c190 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1c1a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1c1b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c1c0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1c1d0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1c1e0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1c1f0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1c200 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c210 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1c220 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1c230 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1c240 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1c250 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1c260 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1c270 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1c280 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1c290 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1c2a0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1c2b0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c2c0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1c2d0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1c2e0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1c2f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c300 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1c310 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1c320 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1c330 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1c340 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1c350 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1c360 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1c370 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c380 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1c390 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1c3a0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1c3b0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1c3c0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1c3d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1c3e0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1c3f0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1c400 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1c410 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1c420 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1c430 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1c440 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1c450 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1c460 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1c470 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1c480 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1c490 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c4a0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1c4b0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1c4c0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1c4d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c4e0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1c4f0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1c500 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1c510 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1c520 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1c530 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1c540 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1c550 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54   reset..*/.SQLIT
1c560 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
1c570 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1c580 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53  ry_used(void);.S
1c590 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1c5a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1c5b0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1c5c0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
1c5d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c5e0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
1c5f0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
1c600 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
1c610 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
1c620 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
1c630 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
1c640 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
1c650 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
1c660 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
1c670 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
1c680 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
1c690 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
1c6a0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
1c6b0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
1c6c0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
1c6d0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
1c6e0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
1c6f0 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
1c700 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
1c710 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
1c720 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
1c730 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
1c740 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
1c750 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
1c760 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
1c770 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
1c780 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1c790 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
1c7a0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
1c7b0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
1c7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1c7d0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
1c7e0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
1c7f0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
1c800 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
1c810 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
1c820 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
1c830 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1c840 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
1c850 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1c860 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
1c870 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1c880 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1c890 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
1c8a0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
1c8b0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1c8c0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1c8d0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1c8e0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1c8f0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1c900 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1c910 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1c920 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
1c930 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61   void sqlite3_ra
1c940 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1c950 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1c960 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1c970 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1c980 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1c990 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1c9a0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1c9b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c9c0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1c9d0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1c9e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1c9f0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1ca00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1ca10 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1ca20 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1ca30 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1ca40 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1ca50 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1ca60 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1ca70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1ca80 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1ca90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1caa0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1cab0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1cac0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1cad0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1cae0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1caf0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1cb00 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1cb10 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1cb20 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1cb30 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1cb40 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1cb50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1cb60 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1cb70 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1cb80 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1cb90 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1cba0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1cbb0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1cbc0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1cbd0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1cbe0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1cbf0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1cc00 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1cc10 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1cc20 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1cc30 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1cc40 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1cc50 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1cc60 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1cc70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1cc80 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1cc90 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1cca0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1ccb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1ccc0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1ccd0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1cce0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1ccf0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1cd00 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1cd10 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1cd20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1cd30 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1cd40 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1cd50 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1cd60 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1cd70 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1cd80 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1cd90 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1cda0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1cdb0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1cdc0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1cdd0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1cde0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1cdf0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1ce00 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1ce10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ce20 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1ce30 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1ce40 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1ce50 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1ce60 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1ce70 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1ce80 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1ce90 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1cea0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1ceb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1cec0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ced0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1cee0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1cef0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1cf00 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1cf10 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1cf20 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1cf30 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1cf40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1cf50 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1cf60 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1cf70 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1cf80 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1cf90 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1cfa0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1cfb0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1cfc0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1cfd0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1cfe0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1cff0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1d000 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1d010 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1d020 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1d030 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1d040 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1d050 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1d060 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1d070 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1d080 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d090 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1d0a0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1d0b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d0c0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1d0d0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1d0e0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1d0f0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1d100 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1d110 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1d120 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1d130 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1d140 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1d150 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1d160 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1d170 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1d180 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1d190 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1d1a0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1d1b0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1d1c0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1d1d0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1d1e0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1d1f0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1d200 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1d210 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1d220 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1d230 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1d240 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1d250 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1d260 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1d270 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1d280 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1d290 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1d2a0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1d2b0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1d2c0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1d2d0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1d2e0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1d2f0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1d300 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1d310 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1d320 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1d330 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1d340 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1d350 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1d360 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1d370 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1d380 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1d390 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1d3a0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1d3b0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1d3c0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1d3d0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1d3e0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1d3f0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1d400 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1d410 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1d420 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1d430 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1d440 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1d450 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1d460 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1d470 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1d480 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1d490 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1d4a0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1d4b0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1d4c0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1d4d0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1d4e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1d4f0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1d500 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1d510 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1d520 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1d530 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1d540 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1d550 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1d560 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1d570 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1d580 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1d590 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1d5a0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1d5b0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1d5c0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1d5d0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1d5e0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1d5f0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1d600 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1d610 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1d620 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1d630 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1d640 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1d650 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1d660 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d670 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1d680 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1d690 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1d6a0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1d6b0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1d6c0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1d6d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d6e0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1d6f0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1d700 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1d710 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1d720 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1d730 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d740 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1d750 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1d760 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1d770 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d780 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1d790 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1d7a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1d7b0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1d7c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d7d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1d7e0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1d7f0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1d800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1d810 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1d820 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1d830 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1d840 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1d850 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d860 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1d870 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1d880 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1d890 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1d8a0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1d8b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d8c0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1d8d0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1d8e0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1d8f0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1d900 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1d910 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1d920 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1d930 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1d940 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1d950 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1d960 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1d970 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d980 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1d990 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1d9a0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1d9b0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1d9c0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1d9d0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1d9e0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1d9f0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1da00 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1da10 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1da20 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1da30 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1da40 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1da50 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1da60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1da70 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1da80 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1da90 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1daa0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
1dab0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74   int sqlite3_set
1dac0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1dad0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1dae0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1daf0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1db00 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1db10 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1db20 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1db30 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1db40 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1db50 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1db60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1db70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1db80 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1db90 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1dba0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1dbb0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1dbc0 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1dbd0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1dbe0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1dbf0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1dc00 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1dc10 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1dc20 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1dc30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1dc40 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1dc50 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1dc60 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1dc70 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1dc80 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1dc90 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1dca0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1dcb0 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1dcc0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1dcd0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1dce0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1dcf0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1dd00 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1dd10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1dd20 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1dd30 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1dd40 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1dd50 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1dd60 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1dd70 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1dd80 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1dd90 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1dda0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1ddb0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1ddc0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1ddd0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1dde0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1ddf0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1de00 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1de10 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1de20 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1de30 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1de40 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1de50 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1de60 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1de70 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1de80 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1de90 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1dea0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1deb0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1dec0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1ded0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1dee0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1def0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1df00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1df10 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1df20 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1df30 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1df40 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1df50 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1df60 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1df70 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1df80 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1df90 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1dfa0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1dfb0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1dfc0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1dfd0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1dfe0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1dff0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1e000 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1e010 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1e020 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1e030 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1e040 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1e050 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1e060 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1e070 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1e080 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1e090 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1e0a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1e0b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e0c0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1e0d0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1e0e0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1e0f0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1e100 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1e110 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1e120 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1e130 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1e140 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1e150 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1e160 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1e170 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e180 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e190 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1e1a0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1e1b0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1e1c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e1d0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1e1e0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1e1f0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1e200 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e210 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e220 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1e230 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e240 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e250 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e260 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1e270 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1e280 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1e290 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e2a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e2b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1e2c0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1e2d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e2e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e2f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e300 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1e310 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1e320 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1e330 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e340 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e350 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1e360 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1e370 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1e380 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e390 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e3a0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1e3b0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1e3c0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1e3d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e3e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e3f0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1e400 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1e410 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1e420 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e430 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e440 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1e450 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1e460 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e470 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e480 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e490 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1e4a0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1e4b0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1e4c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e4d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e4e0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1e4f0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1e500 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e510 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e520 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e530 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1e540 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1e550 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e560 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e570 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e580 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1e590 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1e5a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e5b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e5c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e5d0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1e5e0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1e5f0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1e600 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e610 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e620 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1e630 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1e640 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1e650 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e660 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1e670 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1e680 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1e690 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1e6a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e6b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1e6c0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1e6d0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1e6e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e6f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e700 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1e710 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1e720 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1e730 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e740 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e750 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1e760 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1e770 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1e780 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1e790 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1e7a0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1e7b0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1e7c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e7d0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1e7e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e7f0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1e800 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1e810 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1e820 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e830 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e840 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1e850 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1e860 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1e870 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e880 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e890 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1e8a0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1e8b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e8c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1e8d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e8e0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1e8f0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1e900 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1e910 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e920 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e930 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1e940 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1e950 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1e960 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e970 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e980 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1e990 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1e9a0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1e9b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e9c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1e9d0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1e9e0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1e9f0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1ea00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ea10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1ea20 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1ea30 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1ea40 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1ea50 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ea60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ea70 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1ea80 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1ea90 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1eaa0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1eab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1eac0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1ead0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1eae0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1eaf0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1eb00 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1eb10 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1eb20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1eb30 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1eb40 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1eb50 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1eb60 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1eb70 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1eb80 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1eb90 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1eba0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1ebb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1ebc0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1ebd0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1ebe0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1ebf0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1ec00 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1ec10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1ec20 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1ec30 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1ec40 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1ec50 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1ec60 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1ec70 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1ec80 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1ec90 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1eca0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1ecb0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1ecc0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1ecd0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1ece0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1ecf0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1ed00 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1ed10 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1ed20 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1ed30 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1ed40 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1ed50 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1ed60 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1ed70 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1ed80 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1ed90 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1eda0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1edb0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1edc0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1edd0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1ede0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1edf0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1ee00 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1ee10 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1ee20 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1ee30 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1ee40 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1ee50 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1ee60 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
1ee70 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
1ee80 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
1ee90 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
1eea0 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
1eeb0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
1eec0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
1eed0 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
1eee0 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
1eef0 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
1ef00 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1ef10 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1ef20 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1ef30 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
1ef40 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
1ef50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1ef60 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
1ef70 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1ef80 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1ef90 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1efa0 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1efb0 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1efc0 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1efd0 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1efe0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1eff0 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
1f000 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
1f010 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
1f020 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
1f030 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
1f040 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1f050 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
1f060 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
1f070 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
1f080 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
1f090 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
1f0a0 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
1f0b0 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
1f0c0 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
1f0d0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
1f0e0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
1f0f0 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
1f100 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
1f110 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
1f120 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
1f130 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
1f140 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
1f150 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1f160 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1f170 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1f180 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1f190 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
1f1a0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1f1b0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
1f1c0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
1f1d0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
1f1e0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
1f1f0 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45  _API SQLITE_EXPE
1f200 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1f210 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1f220 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1f230 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1f240 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1f250 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1f260 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1f270 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1f280 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1f290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f2a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1f2b0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
1f2c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
1f2d0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
1f2e0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
1f2f0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1f300 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1f310 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
1f320 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
1f330 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
1f340 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
1f350 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1f360 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
1f370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
1f380 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1f390 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1f3a0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1f3b0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1f3c0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1f3d0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
1f3e0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
1f3f0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
1f400 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
1f410 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
1f420 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f430 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
1f440 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d  ter N is the num
1f450 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
1f460 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
1f470 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
1f480 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
1f490 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
1f4a0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
1f4b0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
1f4c0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
1f4d0 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
1f4e0 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
1f4f0 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
1f500 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
1f510 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
1f520 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
1f530 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1f540 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
1f550 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
1f560 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
1f570 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
1f580 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1f590 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
1f5a0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
1f5b0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
1f5c0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
1f5d0 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
1f5e0 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
1f5f0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1f600 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1f610 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
1f620 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
1f630 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
1f640 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
1f650 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1f660 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
1f670 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
1f680 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
1f690 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
1f6a0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1f6b0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1f6c0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1f6d0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1f6e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1f6f0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1f700 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
1f710 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
1f720 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1f730 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f740 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1f750 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1f760 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1f770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1f780 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1f790 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1f7a0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1f7b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1f7c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1f7d0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1f7e0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1f7f0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1f800 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f810 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1f820 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1f830 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
1f840 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
1f850 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
1f860 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
1f870 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1f880 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1f890 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
1f8a0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1f8b0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1f8c0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1f8d0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1f8e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1f8f0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1f900 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1f910 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1f920 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
1f930 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
1f940 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1f950 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
1f960 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
1f970 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
1f980 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
1f990 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
1f9a0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
1f9b0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
1f9c0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1f9d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
1f9e0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
1f9f0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
1fa00 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
1fa10 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
1fa20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1fa30 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
1fa40 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
1fa50 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1fa60 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1fa70 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1fa80 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1fa90 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1faa0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1fab0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1fac0 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
1fad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1fae0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1faf0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1fb00 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1fb10 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1fb20 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1fb30 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1fb40 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
1fb50 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
1fb60 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
1fb70 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
1fb80 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
1fb90 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
1fba0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1fbb0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1fbc0 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1fbd0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1fbe0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1fbf0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1fc00 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1fc10 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1fc20 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1fc30 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1fc40 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1fc50 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1fc60 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1fc70 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1fc80 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1fc90 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1fca0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1fcb0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1fcc0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1fcd0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1fce0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1fcf0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1fd00 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1fd10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1fd20 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1fd30 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1fd40 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1fd50 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1fd60 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1fd70 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1fd80 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1fd90 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1fda0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1fdb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
1fdc0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1fdd0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
1fde0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
1fdf0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1fe00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1fe10 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1fe20 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1fe30 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1fe40 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1fe50 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1fe60 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
1fe70 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1fe80 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
1fe90 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1fea0 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
1feb0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1fec0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1fed0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1fee0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1fef0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1ff00 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1ff10 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1ff20 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1ff30 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1ff40 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1ff50 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1ff60 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1ff70 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1ff80 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1ff90 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1ffa0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1ffb0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1ffc0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1ffd0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1ffe0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1fff0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
20000 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
20010 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
20020 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
20030 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
20040 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
20050 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
20060 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
20070 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
20080 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
20090 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
200a0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
200b0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
200c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
200d0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
200e0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
200f0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
20100 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
20110 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
20120 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
20130 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
20140 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
20150 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
20160 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
20170 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
20180 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
20190 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
201a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
201b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
201c0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
201d0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
201e0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
201f0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
20200 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
20210 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20220 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
20230 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
20240 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
20250 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
20260 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
20270 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
20280 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
20290 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
202a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
202b0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
202c0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
202d0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
202e0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
202f0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
20300 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
20310 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
20320 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
20330 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
20340 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
20350 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
20360 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
20370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
20380 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
20390 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
203a0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
203b0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
203c0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
203d0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
203e0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
203f0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
20400 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
20410 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
20420 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
20430 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
20440 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
20450 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
20460 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
20470 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
20480 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
20490 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
204a0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
204b0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
204c0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
204d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
204e0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
204f0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
20500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20510 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
20520 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
20530 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
20540 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
20550 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
20560 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
20570 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
20580 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
20590 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
205a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
205b0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
205c0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
205d0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
205e0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
205f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20600 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
20610 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
20620 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
20630 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
20640 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
20650 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
20660 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
20670 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
20680 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
20690 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
206a0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
206b0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
206c0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
206d0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
206e0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
206f0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
20700 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
20710 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20720 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
20730 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
20740 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
20750 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
20760 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
20770 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
20780 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
20790 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
207a0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
207b0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
207c0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
207d0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
207e0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
207f0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
20800 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
20810 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
20820 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
20830 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
20840 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
20850 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
20860 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
20870 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
20880 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
20890 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
208a0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
208b0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
208c0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
208d0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
208e0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
208f0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
20900 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
20910 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
20920 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
20930 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
20940 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
20950 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
20960 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
20970 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
20980 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
20990 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
209a0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
209b0 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
209c0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
209d0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
209e0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
209f0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
20a00 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
20a10 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
20a20 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
20a30 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
20a40 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
20a50 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
20a60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
20a70 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
20a80 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
20a90 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
20aa0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
20ab0 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
20ac0 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
20ad0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
20ae0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
20af0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
20b00 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
20b10 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
20b20 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
20b30 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
20b40 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
20b50 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
20b60 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
20b70 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
20b80 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
20b90 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
20ba0 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
20bb0 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
20bc0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
20bd0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
20be0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
20bf0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
20c00 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
20c10 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
20c20 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
20c30 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
20c40 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
20c50 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
20c60 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
20c70 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
20c80 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
20c90 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
20ca0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
20cb0 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
20cc0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
20cd0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
20ce0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
20cf0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
20d00 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
20d10 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
20d20 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
20d30 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
20d40 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
20d50 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
20d60 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
20d70 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
20d80 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
20d90 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
20da0 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
20db0 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
20dc0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
20dd0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
20de0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
20df0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
20e00 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
20e10 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
20e20 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
20e30 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
20e40 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
20e50 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
20e60 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
20e70 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
20e80 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
20e90 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
20ea0 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
20eb0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
20ec0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
20ed0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
20ee0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
20ef0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
20f00 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
20f10 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
20f20 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
20f30 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
20f40 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
20f50 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
20f60 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
20f70 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
20f80 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
20f90 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
20fa0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
20fb0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
20fc0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
20fd0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
20fe0 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
20ff0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
21000 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
21010 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
21020 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
21030 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
21040 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
21050 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
21060 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
21070 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
21080 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
21090 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
210a0 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
210b0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
210c0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
210d0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
210e0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
210f0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
21100 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
21110 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
21120 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
21130 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
21140 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
21150 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
21160 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
21170 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
21180 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
21190 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
211a0 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
211b0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
211c0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
211d0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
211e0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
211f0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
21200 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21210 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
21220 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
21230 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
21240 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
21250 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
21260 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
21270 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
21280 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
21290 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
212a0 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
212b0 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
212c0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
212d0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
212e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
212f0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21300 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
21310 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
21320 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
21330 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
21340 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
21350 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
21360 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
21370 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21380 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
21390 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
213a0 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
213b0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
213c0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
213d0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
213e0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
213f0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
21400 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
21410 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
21420 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
21430 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
21440 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
21450 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
21460 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
21470 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
21480 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
21490 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
214a0 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
214b0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
214c0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
214d0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
214e0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
214f0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
21500 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
21510 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
21520 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
21530 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
21540 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
21550 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
21560 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
21570 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
21580 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
21590 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
215a0 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
215b0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
215c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
215d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
215e0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
215f0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
21600 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
21610 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
21620 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
21630 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
21640 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
21650 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
21660 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
21670 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
21680 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
21690 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
216a0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
216b0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
216c0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
216d0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
216e0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
216f0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
21700 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
21710 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
21720 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
21730 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
21740 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
21750 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
21760 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
21770 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
21780 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
21790 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
217a0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
217b0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
217c0 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
217d0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
217e0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
217f0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
21800 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
21810 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
21820 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
21830 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
21840 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
21850 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
21860 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
21870 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
21880 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
21890 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
218a0 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
218b0 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
218c0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
218d0 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
218e0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
218f0 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
21900 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
21910 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
21920 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
21930 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
21940 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
21950 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
21960 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
21970 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
21980 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
21990 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
219a0 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
219b0 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
219c0 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
219d0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
219e0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
219f0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
21a00 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
21a10 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
21a20 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
21a30 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
21a40 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
21a50 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
21a60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21a70 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
21a80 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
21a90 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
21aa0 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
21ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
21ac0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
21ad0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
21ae0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
21af0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
21b00 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
21b10 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
21b20 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
21b30 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
21b40 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
21b50 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
21b60 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
21b70 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
21b80 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
21b90 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
21ba0 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
21bb0 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
21bc0 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
21bd0 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
21be0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
21bf0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
21c00 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
21c10 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
21c20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
21c30 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
21c40 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
21c50 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
21c60 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
21c70 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
21c80 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
21c90 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
21ca0 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
21cb0 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
21cc0 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
21cd0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
21ce0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
21cf0 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
21d00 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
21d10 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
21d20 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
21d30 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
21d40 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
21d50 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
21d60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21d70 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
21d80 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
21d90 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
21da0 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
21db0 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
21dc0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
21dd0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
21de0 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
21df0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
21e00 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
21e10 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
21e20 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
21e30 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
21e40 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
21e50 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
21e60 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
21e70 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
21e80 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
21e90 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
21ea0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
21eb0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
21ec0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
21ed0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
21ee0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
21ef0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
21f00 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
21f10 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
21f20 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
21f30 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
21f40 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
21f50 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
21f60 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
21f70 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
21f80 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
21f90 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
21fa0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
21fb0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
21fc0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
21fd0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
21fe0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
21ff0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
22000 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
22010 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
22020 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
22030 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
22040 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
22050 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
22060 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
22070 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
22080 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
22090 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
220a0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
220b0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
220c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
220d0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
220e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
220f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
22100 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
22110 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
22120 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
22130 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
22140 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
22150 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
22160 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
22170 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
22180 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
22190 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
221a0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
221b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
221c0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
221d0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
221e0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
221f0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
22200 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
22210 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
22220 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
22230 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
22240 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
22250 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
22260 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
22270 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
22280 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
22290 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
222a0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
222b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
222c0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
222d0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
222e0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
222f0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
22300 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
22310 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
22320 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
22330 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53  _directory].*/.S
22340 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
22350 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
22360 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
22370 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
22380 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
22390 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
223a0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
223b0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
223c0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53  b handle */.);.S
223d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
223e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
223f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
22400 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
22410 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
22420 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
22430 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
22440 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
22450 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
22460 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
22470 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22480 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
22490 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
224a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
224b0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
224c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
224d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
224e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
224f0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
22500 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
22510 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
22520 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
22530 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
22540 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
22550 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
22560 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
22570 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
22580 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
22590 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
225a0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
225b0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
225c0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
225d0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
225e0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
225f0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
22600 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
22610 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
22620 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
22630 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
22640 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
22650 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
22660 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
22670 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
22680 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
22690 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
226a0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
226b0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
226c0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
226d0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
226e0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
226f0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
22700 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
22710 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
22720 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
22730 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
22740 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
22750 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
22760 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
22770 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
22780 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
22790 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
227a0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
227b0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
227c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
227d0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
227e0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
227f0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
22800 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
22810 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
22820 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
22830 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
22840 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
22850 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
22860 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
22870 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
22880 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
22890 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
228a0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
228b0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
228c0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
228d0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
228e0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
228f0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
22900 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
22910 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
22920 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
22930 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
22940 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
22950 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
22960 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
22970 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
22980 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
22990 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
229a0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
229b0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
229c0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
229d0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
229e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
229f0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
22a00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
22a10 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
22a20 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
22a30 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
22a40 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
22a50 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
22a60 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
22a70 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
22a80 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
22a90 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
22aa0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
22ab0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
22ac0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
22ad0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
22ae0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
22af0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
22b00 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
22b10 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
22b20 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
22b30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
22b40 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
22b50 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
22b60 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
22b70 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
22b80 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
22b90 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
22ba0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
22bb0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
22bc0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
22bd0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
22be0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
22bf0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
22c00 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
22c10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
22c20 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
22c30 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
22c40 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
22c50 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
22c60 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
22c70 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
22c80 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
22c90 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
22ca0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
22cb0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
22cc0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
22cd0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
22ce0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
22cf0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
22d00 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
22d10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
22d20 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
22d30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
22d40 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
22d50 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51  desirable..*/.SQ
22d60 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
22d70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
22d80 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
22d90 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
22da0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
22db0 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50  aram);.SQLITE_AP
22dc0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  I int sqlite3_ur
22dd0 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
22de0 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
22df0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
22e00 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
22e10 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
22e20 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
22e30 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
22e40 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
22e50 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
22e60 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
22e70 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
22e80 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
22e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22ea0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
22eb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
22ec0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
22ed0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
22ee0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
22ef0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
22f00 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
22f10 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
22f20 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
22f30 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
22f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
22f50 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
22f60 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
22f70 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
22f80 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
22f90 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
22fa0 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
22fb0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
22fc0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
22fd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
22fe0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
22ff0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
23000 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
23010 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
23020 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
23030 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
23040 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
23050 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
23060 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
23070 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
23080 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
23090 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
230a0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
230b0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
230c0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
230d0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
230e0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
230f0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
23100 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
23110 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
23120 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
23130 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
23140 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
23150 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
23160 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
23170 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
23180 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
23190 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
231a0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
231b0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
231c0 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
231d0 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
231e0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
231f0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
23200 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
23210 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
23220 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
23230 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23240 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
23250 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
23260 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
23270 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
23280 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
23290 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
232a0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
232b0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
232c0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
232d0 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
232e0 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
232f0 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
23300 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
23310 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
23320 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
23330 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
23340 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
23350 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
23360 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
23370 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
23380 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
23390 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
233a0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
233b0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
233c0 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
233d0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
233e0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
233f0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
23400 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
23410 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
23420 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
23430 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
23440 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
23450 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
23460 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
23470 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
23480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23490 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
234a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
234b0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
234c0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
234d0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
234e0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
234f0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
23500 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
23510 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
23520 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
23530 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
23540 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
23550 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
23560 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
23570 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
23580 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
23590 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
235a0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
235b0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
235c0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
235d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
235e0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
235f0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
23600 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
23610 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
23620 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
23630 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  I int sqlite3_er
23640 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
23650 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
23660 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
23670 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
23680 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
23690 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
236a0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
236b0 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
236c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
236d0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
236e0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  16(sqlite3*);.SQ
236f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
23700 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
23710 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  str(int);../*.**
23720 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
23730 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
23740 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
23750 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23760 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
23770 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
23780 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
23790 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
237a0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
237b0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
237c0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
237d0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
237e0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
237f0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
23800 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
23810 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
23820 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
23830 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
23840 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
23850 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
23860 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
23870 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
23880 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
23890 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
238a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
238b0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
238c0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
238d0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
238e0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
238f0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
23900 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
23910 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
23920 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
23930 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
23940 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
23950 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
23960 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
23970 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
23980 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
23990 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
239a0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
239b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
239c0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
239d0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
239e0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
239f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
23a00 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
23a10 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
23a20 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
23a30 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
23a40 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
23a50 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
23a60 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
23a70 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
23a80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
23a90 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
23aa0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
23ab0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
23ac0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
23ad0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
23ae0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
23af0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
23b00 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
23b10 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
23b20 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
23b30 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
23b40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
23b50 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
23b60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
23b70 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
23b80 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
23b90 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
23ba0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
23bb0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
23bc0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
23bd0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
23be0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
23bf0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
23c00 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
23c10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
23c20 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
23c30 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
23c40 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
23c50 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
23c60 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
23c70 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
23c80 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
23c90 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
23ca0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
23cb0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
23cc0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
23cd0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
23ce0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
23cf0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
23d00 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
23d10 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
23d20 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
23d30 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
23d40 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
23d50 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
23d60 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
23d70 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
23d80 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
23d90 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
23da0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
23db0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
23dc0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
23dd0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
23de0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
23df0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
23e00 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
23e10 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
23e20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
23e30 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
23e40 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
23e50 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
23e60 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
23e70 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
23e80 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
23e90 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
23ea0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
23eb0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
23ec0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
23ed0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
23ee0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
23ef0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
23f00 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
23f10 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
23f20 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
23f30 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
23f40 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
23f50 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
23f60 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
23f70 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
23f80 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
23f90 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
23fa0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
23fb0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
23fc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
23fd0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
23fe0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
23ff0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
24000 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
24010 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
24020 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
24030 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
24040 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
24050 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
24060 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
24070 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
24080 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
24090 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
240a0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
240b0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
240c0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
240d0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
240e0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
240f0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
24100 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
24110 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
24120 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
24130 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
24140 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
24150 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
24160 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
24170 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
24180 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
24190 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
241a0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
241b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
241c0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
241d0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
241e0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
241f0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
24200 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
24210 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
24220 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
24230 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
24240 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
24250 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
24260 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
24270 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
24280 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
24290 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
242a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
242b0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
242c0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
242d0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
242e0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
242f0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
24300 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
24310 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
24320 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
24330 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
24340 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
24350 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
24360 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
24370 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
24380 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
24390 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
243a0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
243b0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
243c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
243d0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
243e0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
243f0 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
24400 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
24410 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
24420 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
24430 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
24440 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24450 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
24460 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
24470 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
24480 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
24490 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
244a0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
244b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
244c0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
244d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
244e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
244f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
24500 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
24510 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
24520 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
24530 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
24540 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
24550 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24560 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
24570 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
24580 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
24590 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
245a0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
245b0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
245c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
245d0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
245e0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
245f0 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
24600 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
24610 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24620 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
24630 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24640 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
24650 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24660 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
24670 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
24680 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
24690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
246a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
246b0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
246c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
246d0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
246e0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
246f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
24700 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
24710 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
24720 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
24730 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24740 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
24750 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24760 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
24770 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24780 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
24790 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
247a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
247b0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
247c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
247d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
247e0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
247f0 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
24800 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
24810 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
24820 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
24830 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
24840 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
24850 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
24860 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
24870 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
24880 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24890 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
248a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
248b0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
248c0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
248d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
248e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
248f0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
24900 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
24910 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
24920 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
24930 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
24940 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
24950 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
24960 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
24970 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
24980 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
24990 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
249a0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
249b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
249c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
249d0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
249e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
249f0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
24a00 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
24a10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24a20 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
24a30 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
24a40 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24a50 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
24a60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24a70 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
24a80 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
24a90 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
24aa0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
24ab0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24ac0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
24ad0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
24ae0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
24af0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
24b00 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
24b10 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
24b20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
24b30 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
24b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24b50 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
24b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24b70 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
24b80 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
24b90 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
24ba0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
24bb0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
24bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24bd0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
24be0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
24bf0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
24c00 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
24c10 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
24c20 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
24c30 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
24c40 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
24c50 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
24c60 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
24c70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
24c80 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
24c90 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
24ca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
24cb0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
24cc0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
24cd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
24ce0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
24cf0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
24d00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
24d10 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
24d20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
24d30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24d40 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
24d50 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
24d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
24d70 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
24d80 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
24d90 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
24da0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
24db0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
24dc0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
24dd0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
24de0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
24df0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
24e00 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
24e10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
24e20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
24e30 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
24e40 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
24e50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
24e60 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
24e70 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
24e80 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24e90 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
24ea0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
24eb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
24ec0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
24ed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24ee0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
24ef0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
24f00 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
24f10 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
24f20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
24f30 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
24f40 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
24f50 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
24f60 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
24f70 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
24f80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24f90 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
24fa0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
24fb0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
24fc0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
24fd0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
24fe0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
24ff0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
25000 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
25010 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
25020 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
25030 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
25040 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
25050 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
25060 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
25070 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
25080 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
25090 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
250a0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
250b0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
250c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
250d0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
250e0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
250f0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
25100 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
25110 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
25120 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
25130 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
25140 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
25150 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
25160 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
25170 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
25180 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
25190 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
251a0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
251b0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
251c0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
251d0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
251e0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
251f0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
25200 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
25210 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
25220 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
25230 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
25240 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
25250 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
25260 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
25270 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
25280 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
25290 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
252a0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
252b0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
252c0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
252d0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
252e0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
252f0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
25300 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
25310 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
25320 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
25330 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
25340 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
25350 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
25360 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
25370 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
25380 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
25390 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
253a0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
253b0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
253c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
253d0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
253e0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
253f0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
25400 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
25410 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
25420 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
25430 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
25440 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
25450 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
25460 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
25470 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
25480 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
25490 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
254a0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
254b0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
254c0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
254d0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
254e0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
254f0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
25500 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
25510 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
25520 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
25530 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
25540 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
25550 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
25560 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
25570 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
25580 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
25590 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
255a0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
255b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
255c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
255d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
255e0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
255f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
25600 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
25610 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
25620 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
25630 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
25640 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
25650 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
25660 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
25670 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
25680 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
25690 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
256a0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
256b0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
256c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
256d0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
256e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
256f0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
25700 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
25710 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
25720 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
25730 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
25740 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
25750 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
25760 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
25770 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
25780 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
25790 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
257a0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
257b0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
257c0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
257d0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
257e0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
257f0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
25800 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
25810 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
25820 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
25830 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
25840 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
25850 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
25860 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
25870 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
25880 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
25890 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
258a0 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
258b0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
258c0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
258d0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
258e0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
258f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
25900 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
25910 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
25920 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
25930 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
25940 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
25950 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
25960 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
25970 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
25980 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
25990 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
259a0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
259b0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
259c0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
259d0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
259e0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
259f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
25a00 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
25a10 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
25a20 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
25a30 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
25a40 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
25a50 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
25a60 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
25a70 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
25a80 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
25a90 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
25aa0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
25ab0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
25ac0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
25ad0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
25ae0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
25af0 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
25b00 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
25b10 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
25b20 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
25b30 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
25b40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
25b50 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
25b60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
25b70 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
25b80 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
25b90 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
25ba0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
25bb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25bc0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
25bd0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
25be0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
25bf0 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
25c00 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
25c10 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
25c20 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
25c30 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
25c40 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
25c50 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
25c60 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
25c70 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
25c80 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
25c90 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
25ca0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
25cb0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
25cc0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
25cd0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
25ce0 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
25cf0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
25d00 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
25d10 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
25d20 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
25d30 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65   enabled..** the
25d40 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
25d50 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ol>.*/.SQLITE_AP
25d60 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
25d70 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
25d80 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25d90 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25da0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
25db0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
25dc0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25dd0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
25de0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
25df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
25e00 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
25e10 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
25e20 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
25e30 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
25e40 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
25e50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25e60 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
25e70 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
25e80 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
25e90 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
25ea0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
25eb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
25ec0 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
25ed0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
25ee0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
25ef0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
25f00 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
25f10 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
25f20 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
25f30 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
25f40 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
25f50 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
25f60 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
25f70 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
25f80 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
25f90 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
25fa0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
25fb0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
25fc0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25fd0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25fe0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25ff0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
26000 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
26010 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
26020 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
26030 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
26040 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26050 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
26060 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
26070 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
26080 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
26090 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
260a0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
260b0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
260c0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
260d0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
260e0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
260f0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
26100 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
26110 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
26120 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
26130 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
26140 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
26150 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
26160 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
26170 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
26180 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
26190 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
261a0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
261b0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
261c0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
261d0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
261e0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
261f0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
26200 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
26210 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
26220 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
26230 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
26240 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
26250 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
26260 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
26270 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
26280 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
26290 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
262a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
262b0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
262c0 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
262d0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
262e0 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
262f0 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
26300 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
26310 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
26320 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
26330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26340 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
26350 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
26360 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
26370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26380 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
26390 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
263a0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
263b0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
263c0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
263d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
263e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
263f0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
26400 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
26410 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
26420 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
26430 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26440 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
26450 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
26460 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
26470 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
26480 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26490 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
264a0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
264b0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
264c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
264d0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
264e0 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
264f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
26500 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
26510 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
26520 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
26530 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
26540 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
26550 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
26560 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
26570 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
26580 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
26590 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
265a0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
265b0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
265c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
265d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
265e0 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
265f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
26600 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
26610 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
26620 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
26630 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
26640 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
26650 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
26660 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
26670 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
26680 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
26690 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
266a0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
266b0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
266c0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
266d0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
266e0 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
266f0 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
26700 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
26710 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
26720 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
26730 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
26740 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
26750 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
26760 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
26770 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26780 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
26790 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
267a0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
267b0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
267c0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
267d0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
267e0 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
267f0 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
26800 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
26810 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
26820 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
26830 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
26840 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
26850 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
26860 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
26870 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
26880 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
26890 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
268a0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
268b0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
268c0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
268d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
268e0 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
268f0 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
26900 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
26910 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
26920 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
26930 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
26940 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
26950 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
26960 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
26970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
26980 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
26990 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
269a0 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
269b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
269c0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
269d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
269e0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
269f0 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
26a00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26a10 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
26a20 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
26a30 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
26a40 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
26a50 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20   has not run to 
26a60 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f  completion and/o
26a70 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65  r has not .** be
26a80 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
26a90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
26aa0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
26ab0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
26ac0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26ad0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
26ae0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
26af0 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
26b00 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
26b10 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
26b20 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
26b30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26b40 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
26b50 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
26b60 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
26b70 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
26b80 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
26b90 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
26ba0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
26bb0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
26bc0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
26bd0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
26be0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26bf0 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
26c00 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
26c10 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
26c20 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
26c30 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
26c40 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
26c50 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
26c60 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
26c70 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
26c80 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
26c90 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
26ca0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
26cb0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
26cc0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
26cd0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
26ce0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
26cf0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
26d00 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
26d10 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
26d20 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
26d30 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
26d40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
26d50 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
26d60 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
26d70 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
26d80 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
26d90 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
26da0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
26db0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
26dc0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
26dd0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
26de0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
26df0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
26e00 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
26e10 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
26e20 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
26e30 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
26e40 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
26e50 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
26e60 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
26e70 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
26e80 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
26e90 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
26ea0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
26eb0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
26ec0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
26ed0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
26ee0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
26ef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
26f00 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
26f10 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
26f20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
26f30 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
26f40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26f50 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
26f60 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
26f70 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
26f80 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
26f90 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
26fa0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
26fb0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
26fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
26fd0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
26fe0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
26ff0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
27000 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
27010 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
27020 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
27030 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
27040 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
27050 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
27060 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
27070 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
27080 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
27090 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
270a0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
270b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
270c0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
270d0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
270e0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
270f0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
27100 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
27110 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
27120 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
27130 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
27140 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
27150 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
27160 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
27170 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
27180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
27190 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
271a0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
271b0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
271c0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
271d0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
271e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
271f0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
27200 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
27210 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
27220 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
27230 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
27240 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
27250 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
27260 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
27270 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
27280 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
27290 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
272a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
272b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
272c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
272d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
272e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
272f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27300 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
27310 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
27320 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
27330 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
27340 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
27350 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
27360 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
27370 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
27380 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27390 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
273a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
273b0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
273c0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
273d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
273e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
273f0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
27400 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
27410 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
27420 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
27430 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
27440 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
27450 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
27460 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
27470 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
27480 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
27490 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
274a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
274b0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
274c0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
274d0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
274e0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
274f0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
27500 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
27510 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
27520 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
27530 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
27540 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
27550 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
27560 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
27570 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
27580 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
27590 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
275a0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
275b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
275c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
275d0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
275e0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
275f0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
27600 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
27610 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
27620 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
27630 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
27640 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
27650 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
27660 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
27670 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
27680 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
27690 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
276a0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
276b0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
276c0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
276d0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
276e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
276f0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
27700 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
27710 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
27720 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
27730 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
27740 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
27750 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
27760 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
27770 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
27780 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
27790 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
277a0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
277b0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
277c0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
277d0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
277e0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
277f0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
27800 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
27810 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
27820 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
27830 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
27840 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
27850 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
27860 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
27870 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
27880 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
27890 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
278a0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
278b0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
278c0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
278d0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
278e0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
278f0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
27900 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
27910 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
27920 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
27930 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
27940 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
27950 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
27960 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
27970 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
27980 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
27990 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
279a0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
279b0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
279c0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
279d0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
279e0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
279f0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
27a00 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
27a10 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
27a20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
27a30 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
27a40 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
27a50 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
27a60 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
27a70 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
27a80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27a90 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
27aa0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
27ab0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
27ac0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
27ad0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
27ae0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
27af0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
27b00 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
27b10 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
27b20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
27b30 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
27b40 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
27b50 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
27b60 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
27b70 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
27b80 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
27b90 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
27ba0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
27bb0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
27bc0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
27bd0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
27be0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
27bf0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
27c00 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
27c10 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
27c20 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
27c30 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
27c40 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
27c50 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
27c60 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
27c70 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
27c80 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
27c90 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
27ca0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
27cb0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
27cc0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
27cd0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
27ce0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
27cf0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
27d00 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
27d10 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
27d20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
27d30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27d40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
27d50 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
27d60 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
27d70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27d80 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
27d90 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
27da0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
27db0 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
27dc0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
27dd0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
27de0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
27df0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
27e00 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
27e10 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
27e20 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
27e30 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
27e40 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
27e50 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
27e60 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
27e70 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
27e80 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
27e90 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
27ea0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
27eb0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
27ec0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
27ed0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27ee0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
27ef0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
27f00 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
27f10 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
27f20 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
27f30 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
27f40 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
27f50 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
27f60 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
27f70 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
27f80 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
27f90 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
27fa0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
27fb0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
27fc0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
27fd0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
27fe0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
27ff0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
28000 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
28010 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
28020 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
28030 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28040 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61  6() then that pa
28050 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
28060 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
28070 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
28080 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
28090 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
280a0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
280b0 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
280c0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
280d0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
280e0 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
280f0 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
28100 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
28110 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28120 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
28130 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
28140 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
28150 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
28160 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
28170 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
28180 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
28190 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
281a0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
281b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
281c0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
281d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
281e0 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
281f0 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
28200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28210 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
28220 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
28230 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
28240 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
28250 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
28260 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
28270 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
28280 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
28290 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
282a0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
282b0 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
282c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
282d0 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69  _blob(),.** sqli
282e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
282f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
28300 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e  _text16() fails.
28310 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69    .** ^If the fi
28320 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
28330 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
28340 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
28350 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
28360 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
28370 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
28380 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
28390 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
283a0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
283b0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
283c0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
283d0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
283e0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
283f0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
28400 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
28410 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
28420 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
28430 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
28440 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
28450 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
28460 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
28470 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28480 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
28490 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
284a0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
284b0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
284c0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
284d0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
284e0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
284f0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
28500 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
28510 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
28520 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
28530 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
28540 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
28550 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
28560 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
28570 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
28580 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
28590 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
285a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
285b0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
285c0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
285d0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
285e0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
285f0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
28600 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
28610 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
28620 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
28630 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
28640 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
28650 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
28660 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
28670 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
28680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
28690 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
286a0 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
286b0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
286c0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
286d0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
286e0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
286f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
28700 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
28710 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
28720 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
28730 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
28740 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
28750 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
28760 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28770 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
28780 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
28790 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
287a0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
287b0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
287c0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
287d0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
287e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
287f0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
28800 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
28810 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
28820 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
28830 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28840 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
28850 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
28860 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
28870 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
28880 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
28890 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
288a0 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
288b0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
288c0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
288d0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
288e0 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
288f0 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
28900 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
28910 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
28920 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28930 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
28940 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
28950 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28960 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
28970 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
28980 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
28990 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
289a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
289b0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
289c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
289d0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
289e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
289f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
28a00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
28a10 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
28a20 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
28a30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
28a40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
28a50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28a60 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  nt, int);.SQLITE
28a70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28a80 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
28a90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28aa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
28ab0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
28ac0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
28ad0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28ae0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
28af0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
28b00 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
28b10 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
28b20 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
28b30 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
28b40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
28b50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28b60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28b70 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
28b80 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
28b90 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
28ba0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28bb0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
28bc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28bd0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
28be0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
28bf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
28c00 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
28c10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28c20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
28c30 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
28c40 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
28c50 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
28c60 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
28c70 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
28c80 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
28c90 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
28ca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28cb0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
28cc0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
28cd0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
28ce0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
28cf0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
28d00 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
28d10 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
28d20 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
28d30 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
28d40 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
28d50 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
28d60 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
28d70 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
28d80 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
28d90 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
28da0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
28db0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
28dc0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
28dd0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
28de0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
28df0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
28e00 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
28e10 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
28e20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
28e30 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
28e40 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
28e50 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
28e60 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
28e70 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
28e80 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
28e90 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
28ea0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
28eb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
28ec0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
28ed0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
28ee0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28ef0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.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 70 61 72 61 6d 65  ite3_bind_parame
28f20 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
28f30 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
28f40 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
28f50 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
28f60 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
28f70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28f80 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
28f90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28fa0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
28fb0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
28fc0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
28fd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28fe0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
28ff0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
29000 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
29010 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
29020 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
29030 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
29040 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
29050 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
29060 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
29070 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
29080 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
29090 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
290a0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
290b0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
290c0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
290d0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
290e0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
290f0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
29100 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
29110 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
29120 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
29130 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
29140 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
29150 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
29160 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
29170 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
29180 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
29190 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
291a0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
291b0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
291c0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
291d0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
291e0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
291f0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
29200 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
29210 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
29220 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
29230 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
29240 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
29250 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
29260 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
29270 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
29280 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
29290 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
292a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
292b0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
292c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
292d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
292e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
292f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29300 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
29310 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
29320 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29330 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
29340 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
29350 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29360 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29370 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
29380 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
29390 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
293a0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
293b0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
293c0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
293d0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
293e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
293f0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
29400 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
29410 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
29420 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
29430 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
29440 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
29450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29460 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
29470 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
29480 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
29490 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
294a0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
294b0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
294c0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
294d0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
294e0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
294f0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
29500 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
29510 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
29520 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
29530 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
29540 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
29550 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
29560 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
29570 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29580 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
29590 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
295a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
295b0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
295c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
295d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
295e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
295f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
29600 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
29610 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29620 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
29630 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
29640 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
29650 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
29660 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
29670 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
29680 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
29690 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
296a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
296b0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
296c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
296d0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
296e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
296f0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
29700 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
29710 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
29720 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
29730 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
29740 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
29750 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
29760 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
29770 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
29780 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
29790 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
297a0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
297b0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
297c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
297d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
297e0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
297f0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
29800 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
29810 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
29820 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
29830 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
29840 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
29850 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29860 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
29870 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
29880 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
29890 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
298a0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
298b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
298c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
298d0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
298e0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
298f0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
29900 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
29910 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
29920 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
29930 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
29940 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
29950 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
29960 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
29970 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
29990 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
299a0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
299b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
299c0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
299d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
299e0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
299f0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
29a00 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
29a10 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
29a20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
29a30 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
29a40 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
29a50 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
29a60 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
29a70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
29a80 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
29a90 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
29aa0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
29ab0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
29ac0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
29ad0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
29ae0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
29af0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29b00 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
29b10 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
29b20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
29b30 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
29b40 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
29b50 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
29b60 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
29b70 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
29b80 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
29b90 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
29ba0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
29bb0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
29bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
29bd0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
29be0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
29bf0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
29c00 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
29c10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
29c20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
29c30 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
29c40 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
29c50 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
29c60 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
29c70 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
29c80 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
29c90 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
29ca0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
29cb0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
29cc0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
29cd0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
29ce0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
29cf0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
29d00 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
29d10 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
29d20 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
29d30 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
29d40 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
29d50 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
29d60 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
29d70 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
29d80 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
29d90 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
29da0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
29db0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29dc0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
29dd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29de0 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
29df0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
29e00 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
29e10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29e20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
29e30 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
29e40 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
29e50 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
29e60 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
29e70 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
29e80 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
29e90 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
29ea0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
29eb0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
29ec0 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
29ed0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
29ee0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
29ef0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
29f00 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
29f10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
29f20 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
29f30 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
29f40 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
29f50 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
29f60 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
29f70 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
29f80 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
29f90 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
29fa0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
29fb0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
29fc0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
29fd0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
29fe0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
29ff0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
2a000 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2a010 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
2a020 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
2a030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2a040 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
2a050 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2a060 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2a070 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2a080 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2a090 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2a0a0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2a0b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2a0c0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2a0d0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2a0e0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
2a0f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
2a100 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
2a110 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
2a120 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
2a130 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
2a140 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
2a150 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
2a160 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
2a170 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2a180 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
2a190 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2a1a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
2a1b0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
2a1c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a1d0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
2a1e0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2a1f0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2a200 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
2a210 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
2a220 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
2a230 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
2a240 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
2a250 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
2a260 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
2a270 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
2a280 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
2a290 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
2a2a0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2a2b0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
2a2c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2a2d0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
2a2e0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
2a2f0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
2a300 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
2a310 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2a320 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
2a330 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
2a340 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
2a350 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
2a360 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2a370 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
2a380 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
2a390 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
2a3a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
2a3b0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
2a3c0 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
2a3d0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
2a3e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
2a3f0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
2a400 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
2a410 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
2a420 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
2a430 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
2a440 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
2a450 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
2a460 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
2a470 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
2a480 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
2a490 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
2a4a0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
2a4b0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
2a4c0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
2a4d0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
2a4e0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
2a4f0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
2a500 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
2a510 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2a520 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2a530 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
2a540 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2a550 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
2a560 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
2a570 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
2a580 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
2a590 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2a5a0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
2a5b0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
2a5c0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2a5d0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2a5e0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
2a5f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2a600 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
2a610 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
2a620 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
2a630 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
2a640 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
2a650 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
2a660 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2a670 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2a680 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2a690 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2a6a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a6b0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2a6c0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2a6d0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2a6e0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2a6f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a700 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2a710 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a720 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2a730 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2a740 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2a750 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2a760 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2a770 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2a780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a790 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2a7a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2a7b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2a7c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2a7d0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2a7e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a7f0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2a800 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2a810 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2a820 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
2a830 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2a840 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2a850 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
2a860 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
2a870 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
2a880 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2a890 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2a8a0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
2a8b0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
2a8c0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
2a8d0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
2a8e0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2a8f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
2a900 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
2a910 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
2a920 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
2a930 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2a940 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
2a950 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
2a960 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
2a970 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2a980 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2a990 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2a9a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2a9b0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2a9c0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2a9d0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2a9e0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2a9f0 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2aa00 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2aa10 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2aa20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2aa30 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2aa40 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2aa50 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2aa60 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2aa70 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2aa80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2aa90 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2aaa0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2aab0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2aac0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2aad0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2aae0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2aaf0 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2ab00 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2ab10 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2ab20 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2ab30 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2ab40 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2ab50 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2ab60 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2ab70 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2ab80 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2ab90 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2aba0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2abb0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2abc0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2abd0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2abe0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2abf0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2ac00 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2ac10 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2ac20 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2ac30 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2ac40 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2ac50 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2ac60 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2ac70 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2ac80 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2ac90 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2aca0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2acb0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2acc0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
2acd0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2ace0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2acf0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
2ad00 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2ad10 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2ad20 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ad30 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2ad40 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2ad50 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2ad60 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2ad70 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2ad80 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2ad90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ada0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2adb0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2adc0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2add0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2ade0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2adf0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2ae00 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2ae10 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2ae20 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2ae30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2ae40 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2ae50 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2ae60 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2ae70 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2ae80 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2ae90 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2aea0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2aeb0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2aec0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2aed0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2aee0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2aef0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2af00 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2af10 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2af20 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2af30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2af40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2af50 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2af60 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2af70 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2af80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2af90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2afa0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2afb0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2afc0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2afd0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2afe0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2aff0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2b000 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2b010 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2b020 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2b030 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2b040 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2b050 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2b060 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2b070 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2b080 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2b090 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2b0a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2b0b0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2b0c0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2b0d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2b0e0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2b0f0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2b100 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2b110 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2b120 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2b130 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2b140 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2b150 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2b160 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2b170 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2b180 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2b190 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2b1a0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2b1b0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2b1c0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2b1d0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2b1e0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2b1f0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2b200 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2b210 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2b220 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2b230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2b240 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2b250 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2b260 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2b270 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2b280 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2b290 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2b2a0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2b2b0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2b2c0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2b2d0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2b2e0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2b2f0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2b300 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2b310 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2b320 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2b330 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2b340 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2b350 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2b360 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2b370 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2b380 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2b390 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2b3a0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2b3b0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2b3c0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2b3d0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2b3e0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2b3f0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2b400 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2b410 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2b420 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2b430 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2b440 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2b450 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2b460 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2b470 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2b480 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2b490 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2b4a0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2b4b0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2b4c0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2b4d0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2b4e0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2b4f0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2b500 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2b510 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2b520 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2b530 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2b540 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2b550 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2b560 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2b570 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2b580 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2b590 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2b5a0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2b5b0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2b5c0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2b5d0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2b5e0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2b5f0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2b600 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2b610 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2b620 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2b630 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2b640 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2b650 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2b660 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2b670 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2b680 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2b690 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2b6a0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2b6b0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2b6c0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2b6d0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2b6e0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2b6f0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2b700 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2b710 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2b720 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2b730 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2b740 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2b750 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2b760 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2b770 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2b780 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2b790 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2b7a0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2b7b0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2b7c0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2b7d0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2b7e0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2b7f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2b800 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2b810 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2b820 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2b830 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2b840 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2b850 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2b860 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2b870 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2b880 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2b890 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2b8a0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2b8b0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2b8c0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2b8d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b8e0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2b8f0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2b900 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2b910 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2b920 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2b930 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2b940 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2b950 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2b960 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2b970 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2b980 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b990 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2b9a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2b9b0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2b9c0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2b9d0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2b9e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2b9f0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2ba00 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2ba10 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2ba20 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2ba30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2ba40 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2ba50 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2ba60 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2ba70 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2ba80 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2ba90 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2baa0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2bab0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2bac0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2bad0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2bae0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2baf0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2bb00 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2bb10 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2bb20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2bb30 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2bb40 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2bb50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2bb60 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2bb70 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2bb80 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2bb90 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2bba0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2bbb0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2bbc0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2bbd0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2bbe0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2bbf0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2bc00 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2bc10 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2bc20 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2bc30 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2bc40 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2bc50 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2bc60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2bc70 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2bc80 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2bc90 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2bca0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2bcb0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2bcc0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2bcd0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2bce0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2bcf0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2bd00 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2bd10 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2bd20 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2bd30 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2bd40 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2bd50 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2bd60 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2bd70 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2bd80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2bd90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2bda0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2bdb0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2bdc0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2bdd0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2bde0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bdf0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2be00 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2be10 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2be20 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2be30 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2be40 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2be50 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2be60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2be70 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2be80 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2be90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65   int sqlite3_ste
2bea0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2beb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bec0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2bed0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2bee0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
2bef0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2bf00 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2bf10 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2bf20 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2bf30 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2bf40 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2bf50 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2bf60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2bf70 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2bf80 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2bf90 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2bfa0 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2bfb0 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2bfc0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2bfd0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2bfe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2bff0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2c000 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2c010 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2c020 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2c030 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2c040 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2c050 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2c060 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2c070 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2c080 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c090 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2c0a0 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2c0b0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2c0c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2c0d0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2c0e0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2c0f0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2c100 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2c110 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2c120 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2c130 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2c140 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2c150 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2c160 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2c170 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2c180 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2c190 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2c1a0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2c1b0 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2c1c0 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2c1d0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2c1e0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2c1f0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2c200 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2c210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2c220 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2c230 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c240 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2c250 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c270 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2c280 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2c290 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2c2a0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2c2b0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2c2c0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2c2d0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2c2e0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2c2f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2c300 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2c310 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2c320 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2c330 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2c340 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2c350 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2c360 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2c370 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2c380 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2c390 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2c3a0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2c3b0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2c3c0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2c3d0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2c3e0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2c3f0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2c400 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2c410 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2c420 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2c430 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2c440 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2c450 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2c460 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2c470 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2c480 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2c490 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2c4a0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2c4b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2c4c0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2c4d0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2c4e0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2c4f0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2c500 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2c510 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2c520 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2c530 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2c540 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2c550 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2c560 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2c570 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2c580 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2c590 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2c5a0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2c5b0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2c5c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2c5d0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2c5e0 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2c5f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2c600 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2c610 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2c620 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2c630 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2c640 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2c650 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2c660 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2c670 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2c680 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2c690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c6a0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2c6b0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2c6c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2c6d0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2c6e0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2c6f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c700 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2c710 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2c720 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2c730 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2c740 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2c750 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2c760 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2c770 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2c780 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2c790 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2c7a0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2c7b0 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2c7c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2c7d0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2c7e0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2c7f0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2c800 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2c810 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2c820 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2c830 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2c840 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2c850 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2c860 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2c870 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2c880 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2c890 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2c8a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2c8b0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2c8c0 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2c8d0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2c8e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c8f0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2c900 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2c910 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2c920 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2c930 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c940 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2c950 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2c960 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2c970 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2c980 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2c990 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2c9a0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2c9b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2c9c0 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2c9d0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2c9e0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2c9f0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2ca00 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2ca10 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2ca20 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2ca30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2ca40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ca50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2ca60 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2ca70 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2ca80 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2ca90 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2caa0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2cab0 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2cac0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2cad0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2cae0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2caf0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2cb00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2cb10 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2cb20 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2cb30 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2cb40 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2cb50 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2cb60 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2cb70 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2cb80 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2cb90 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2cba0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2cbb0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2cbc0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2cbd0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2cbe0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2cbf0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2cc00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2cc10 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2cc20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2cc30 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2cc40 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2cc50 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2cc60 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2cc70 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2cc80 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2cc90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2cca0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2ccb0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2ccc0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2ccd0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2cce0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2ccf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2cd00 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2cd10 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2cd20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2cd30 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2cd40 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2cd50 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2cd60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2cd70 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2cd80 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2cd90 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2cda0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2cdb0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2cdc0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2cdd0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2cde0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2cdf0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2ce00 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2ce10 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2ce20 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2ce30 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2ce40 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2ce50 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2ce60 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ce70 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2ce80 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2ce90 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2cea0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2ceb0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2cec0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2ced0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2cee0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2cef0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2cf00 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2cf10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cf20 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2cf30 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2cf40 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2cf50 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2cf60 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2cf70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cf80 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2cf90 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2cfa0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2cfb0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2cfc0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2cfd0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2cfe0 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2cff0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d000 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2d010 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2d020 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2d030 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2d040 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2d050 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d060 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2d070 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2d080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d090 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2d0a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2d0b0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2d0c0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2d0d0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2d0e0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2d0f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d100 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2d110 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d120 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2d130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d140 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2d150 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2d160 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2d170 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2d180 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2d190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2d1a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2d1b0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2d1c0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2d1d0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2d1e0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2d1f0 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2d200 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2d210 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2d220 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2d230 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2d240 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2d250 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2d260 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2d270 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2d280 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2d290 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2d2a0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2d2b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2d2c0 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2d2d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d2e0 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2d2f0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2d300 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2d310 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2d320 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2d330 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2d340 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2d350 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2d360 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2d370 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2d380 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2d390 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2d3a0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2d3b0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2d3c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d3d0 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
2d3e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d3f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
2d400 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2d410 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
2d420 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
2d430 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d440 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
2d450 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
2d460 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d470 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2d480 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2d490 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2d4a0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
2d4b0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
2d4c0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
2d4d0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2d4e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2d4f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2d500 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2d510 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2d520 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
2d530 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2d540 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2d550 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2d560 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
2d570 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
2d580 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
2d590 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
2d5a0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2d5b0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2d5c0 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2d5d0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2d5e0 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2d5f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2d600 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2d610 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2d620 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2d630 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2d640 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
2d650 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
2d660 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
2d670 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
2d680 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
2d690 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
2d6a0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
2d6b0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
2d6c0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
2d6d0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
2d6e0 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
2d6f0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2d700 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2d710 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2d720 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
2d730 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2d740 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2d750 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2d760 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
2d770 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
2d780 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
2d790 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2d7a0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2d7b0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2d7c0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2d7d0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2d7e0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2d7f0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2d800 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2d810 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2d820 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2d830 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2d840 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2d850 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2d860 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2d870 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2d880 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2d890 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2d8a0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2d8b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2d8c0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2d8d0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2d8e0 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
2d8f0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2d900 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2d910 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2d920 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2d930 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2d940 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2d950 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2d960 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
2d970 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
2d980 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2d990 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2d9a0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
2d9b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2d9c0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2d9d0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
2d9e0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2d9f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
2da00 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
2da10 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
2da20 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2da30 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
2da40 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2da50 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
2da60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2da70 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2da80 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2da90 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2daa0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
2dab0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2dac0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2dad0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2dae0 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2daf0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2db00 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2db10 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2db20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2db30 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2db40 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2db50 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2db60 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2db70 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2db80 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2db90 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2dba0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2dbb0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2dbc0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2dbd0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2dbe0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2dbf0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2dc00 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2dc10 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2dc20 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2dc30 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2dc40 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2dc50 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2dc60 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2dc70 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2dc80 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2dc90 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2dca0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2dcb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2dcc0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2dcd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2dce0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2dcf0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2dd00 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2dd10 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2dd20 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2dd30 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2dd40 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2dd50 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2dd60 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2dd70 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2dd80 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2dd90 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2dda0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2ddb0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2ddc0 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2ddd0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2dde0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2ddf0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2de00 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2de10 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2de20 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2de30 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2de40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2de50 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2de60 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2de70 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2de80 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2de90 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2dea0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2deb0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2dec0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2ded0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2dee0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2def0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2df00 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2df10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2df20 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2df30 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2df40 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2df50 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2df60 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2df70 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2df80 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2df90 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2dfa0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2dfb0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2dfc0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2dfd0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2dfe0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2dff0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2e000 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2e010 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2e020 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2e030 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2e040 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2e050 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2e060 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2e070 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2e080 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2e090 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2e0a0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2e0b0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2e0c0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2e0d0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2e0e0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2e0f0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2e100 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2e110 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2e120 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2e130 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2e140 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2e150 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2e160 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2e170 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2e180 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2e190 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e1a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2e1b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2e1c0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2e1d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e1e0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2e1f0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2e200 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2e210 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2e220 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e230 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2e240 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2e250 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2e260 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2e270 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2e280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e290 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2e2a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e2b0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2e2c0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2e2d0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2e2e0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2e2f0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
2e300 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2e310 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e320 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
2e330 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
2e340 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
2e350 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
2e360 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2e370 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2e380 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2e390 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
2e3a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2e3b0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
2e3c0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
2e3d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2e3e0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
2e3f0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
2e400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e410 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
2e420 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2e430 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
2e440 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
2e450 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
2e460 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
2e470 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
2e480 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2e490 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e4a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e4b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
2e4c0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
2e4d0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
2e4e0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
2e4f0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
2e500 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
2e510 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
2e520 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
2e530 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
2e540 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e550 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2e560 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2e570 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
2e580 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2e590 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
2e5a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2e5b0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2e5c0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
2e5d0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
2e5e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
2e5f0 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
2e600 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
2e610 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2e620 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
2e630 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
2e640 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2e650 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
2e660 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
2e670 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
2e680 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2e690 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
2e6a0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
2e6b0 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53  E_NOMEM].)^.*/.S
2e6c0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2e6d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2e6e0 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2e6f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e700 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2e710 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2e720 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
2e730 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e740 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2e750 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e760 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
2e770 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e780 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
2e790 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2e7a0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2e7b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e7c0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2e7d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2e7e0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2e7f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2e800 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
2e810 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2e820 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2e830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e840 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2e850 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
2e860 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2e870 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
2e880 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e890 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2e8a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2e8b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e8c0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2e8d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2e8e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e8f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2e900 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e910 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2e920 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c  _API sqlite3_val
2e930 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2e940 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2e950 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e960 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e970 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2e980 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2e990 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2e9a0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2e9b0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2e9c0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2e9d0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2e9e0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2e9f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2ea00 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2ea10 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2ea20 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2ea30 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2ea40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2ea50 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2ea60 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2ea70 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2ea80 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2ea90 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2eaa0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2eab0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2eac0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2ead0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2eae0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2eaf0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2eb00 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2eb10 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2eb20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2eb30 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2eb40 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2eb50 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2eb60 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2eb70 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2eb80 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2eb90 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2eba0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2ebb0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2ebc0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2ebd0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2ebe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2ebf0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2ec00 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2ec10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ec20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2ec30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2ec40 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2ec50 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2ec60 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2ec70 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2ec80 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2ec90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2eca0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2ecb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2ecc0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2ecd0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2ece0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ecf0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2ed00 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2ed10 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2ed20 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2ed30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ed40 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2ed50 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2ed60 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2ed70 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2ed80 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2ed90 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2eda0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2edb0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2edc0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2edd0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2ede0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2edf0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2ee00 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2ee10 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2ee20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2ee30 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2ee40 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2ee50 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2ee60 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2ee70 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2ee80 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2ee90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2eea0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2eeb0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2eec0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2eed0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2eee0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2eef0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2ef00 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2ef10 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2ef20 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2ef30 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2ef40 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2ef50 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2ef60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ef70 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2ef80 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2ef90 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2efa0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2efb0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2efc0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2efd0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2efe0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2eff0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2f000 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2f010 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f020 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2f030 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2f040 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2f050 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2f060 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2f070 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2f080 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2f090 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f0a0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2f0b0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2f0c0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2f0d0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2f0e0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2f0f0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2f100 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2f110 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f120 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2f130 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2f140 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2f150 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2f160 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2f170 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2f180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2f190 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2f1a0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2f1b0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2f1c0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2f1d0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2f1e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2f1f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2f200 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2f210 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2f220 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2f230 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2f240 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2f250 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f260 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53  atement] S..*/.S
2f270 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2f280 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2f290 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2f2a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f2b0 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2f2c0 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2f2d0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
2f2e0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2f2f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2f300 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2f310 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2f330 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2f340 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f350 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2f360 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2f370 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2f380 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2f390 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2f3a0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2f3b0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2f3c0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2f3d0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2f3e0 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2f3f0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2f400 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2f410 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2f420 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2f430 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
2f440 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
2f450 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
2f460 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
2f470 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
2f480 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
2f490 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
2f4a0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
2f4b0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
2f4c0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
2f4d0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
2f4e0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
2f4f0 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
2f500 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2f510 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
2f520 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2f530 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2f540 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2f550 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2f560 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2f570 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
2f580 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
2f590 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
2f5a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2f5b0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
2f5c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f5d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2f5e0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
2f5f0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2f600 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
2f610 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
2f620 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2f630 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2f640 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2f650 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
2f660 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
2f670 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
2f680 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2f690 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2f6a0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
2f6b0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
2f6c0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2f6d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2f6e0 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
2f6f0 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
2f700 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
2f710 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
2f720 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
2f730 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
2f740 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
2f750 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2f760 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2f770 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2f780 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
2f790 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
2f7a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2f7b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2f7c0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2f7d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2f7e0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2f7f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2f800 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2f810 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
2f820 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
2f830 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2f840 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2f850 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2f860 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2f870 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
2f880 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
2f890 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
2f8a0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2f8b0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2f8c0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
2f8d0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
2f8e0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
2f8f0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2f900 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
2f910 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
2f920 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2f930 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f940 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2f950 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2f960 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2f970 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2f980 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2f990 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2f9a0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2f9b0 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69  Every SQL functi
2f9c0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2f9d0 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74  n must be able t
2f9e0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55  o work.** with U
2f9f0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
2fa00 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
2fa10 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
2fa20 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
2fa30 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
2fa40 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
2fa50 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
2fa60 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2fa70 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
2fa80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fa90 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2faa0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fab0 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2fac0 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2fad0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2fae0 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2faf0 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2fb00 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
2fb10 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2fb20 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2fb30 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2fb40 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2fb50 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2fb60 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2fb70 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2fb80 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2fb90 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2fba0 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2fbb0 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2fbc0 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2fbd0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2fbe0 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2fbf0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2fc00 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2fc10 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2fc20 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2fc30 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
2fc40 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2fc50 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2fc60 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2fc70 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2fc80 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2fc90 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2fca0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2fcb0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2fcc0 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
2fcd0 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
2fce0 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
2fcf0 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2fd00 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2fd10 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2fd20 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2fd30 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2fd40 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2fd50 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2fd60 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
2fd70 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2fd80 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2fd90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2fda0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2fdb0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
2fdc0 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
2fdd0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2fde0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2fdf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2fe00 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
2fe10 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2fe20 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2fe30 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2fe40 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2fe50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
2fe60 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
2fe70 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
2fe80 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
2fe90 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
2fea0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
2feb0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
2fec0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2fed0 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
2fee0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
2fef0 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
2ff00 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2ff10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2ff20 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
2ff30 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
2ff40 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2ff50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2ff60 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
2ff70 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2ff80 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
2ff90 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
2ffa0 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
2ffb0 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
2ffc0 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
2ffd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2ffe0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
2fff0 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
30000 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
30010 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
30020 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
30030 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
30040 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
30050 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
30060 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
30070 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
30080 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
30090 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
300a0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
300b0 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
300c0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
300d0 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
300e0 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
300f0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
30100 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
30110 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
30120 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
30130 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
30140 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
30150 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
30160 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
30170 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
30180 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
30190 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
301a0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
301b0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
301c0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
301d0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
301e0 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
301f0 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
30200 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
30210 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
30220 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
30230 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
30240 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
30250 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
30260 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
30270 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
30280 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
30290 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
302a0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
302b0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
302c0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
302d0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
302e0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
302f0 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
30300 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
30310 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
30320 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
30330 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
30340 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
30350 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
30360 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
30370 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
30380 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
30390 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
303a0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
303b0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
303c0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
303d0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
303e0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
303f0 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
30400 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
30410 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
30420 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
30430 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
30440 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
30450 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
30460 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30470 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
30480 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30490 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
304a0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
304b0 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
304c0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
304d0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
304e0 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
304f0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
30500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
30510 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
30520 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
30530 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
30540 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
30550 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
30560 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
30570 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30580 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
30590 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
305a0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
305b0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
305c0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
305d0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
305e0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
305f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30600 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
30610 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
30620 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
30630 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
30640 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
30650 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
30660 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
30670 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
30680 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
30690 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
306a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
306b0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
306c0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
306d0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
306e0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
306f0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
30700 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
30710 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
30720 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
30730 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
30740 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
30750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
30760 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
30770 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
30780 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
30790 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
307a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
307b0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
307c0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
307d0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
307e0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
307f0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
30800 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
30810 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
30820 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30830 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30840 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
30850 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30860 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
30870 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
30880 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
30890 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
308a0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
308b0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
308c0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
308d0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
308e0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
308f0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
30900 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
30910 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
30920 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
30930 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
30940 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
30950 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
30960 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
30970 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
30980 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
30990 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
309a0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
309b0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
309c0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
309d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
309e0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
309f0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
30a00 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
30a10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30a20 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
30a30 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
30a40 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
30a50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30a60 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
30a70 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
30a80 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
30a90 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
30aa0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
30ab0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
30ac0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
30ad0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
30ae0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
30af0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
30b00 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
30b10 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
30b20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
30b30 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
30b40 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
30b50 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
30b60 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
30b70 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
30b80 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
30b90 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
30ba0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
30bb0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
30bc0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
30bd0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
30be0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
30bf0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
30c00 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
30c10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
30c20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30c30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
30c40 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
30c50 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
30c60 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
30c70 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
30c80 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
30c90 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
30ca0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
30cb0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
30cc0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
30cd0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
30ce0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
30cf0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
30d00 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
30d10 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
30d20 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
30d30 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
30d40 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30d50 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
30d60 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
30d70 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
30d80 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30d90 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
30da0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
30db0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
30dc0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
30dd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30de0 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
30df0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
30e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30e10 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
30e20 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
30e30 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
30e40 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
30e50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
30e60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
30e70 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
30e80 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
30e90 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
30ea0 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
30eb0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
30ec0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
30ed0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
30ee0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
30ef0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
30f00 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
30f10 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
30f20 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
30f30 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
30f40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
30f50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
30f60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
30f70 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
30f80 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
30f90 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
30fa0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
30fb0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
30fc0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
30fd0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
30fe0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
30ff0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
31000 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31010 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
31020 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
31030 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
31040 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
31050 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
31060 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31070 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
31080 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
31090 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
310a0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
310b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
310c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
310d0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
310e0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
310f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31100 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
31110 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
31120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
31130 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
31140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
31150 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
31160 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
31170 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
31180 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
31190 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
311a0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
311b0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
311c0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
311d0 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
311e0 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
311f0 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
31200 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31210 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
31220 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
31230 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
31240 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
31250 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
31260 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
31270 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
31280 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
31290 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
312a0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
312b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
312c0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
312d0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
312e0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
312f0 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
31300 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
31310 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
31320 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
31330 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
31340 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
31350 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
31360 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
31370 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
31380 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
31390 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
313a0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
313b0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
313c0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
313d0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
313e0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
313f0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
31400 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
31410 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
31420 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
31430 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
31440 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
31450 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
31460 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
31470 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
31480 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
31490 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
314a0 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
314b0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
314c0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
314d0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
314e0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
314f0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
31500 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
31510 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
31520 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
31530 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
31540 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
31550 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
31560 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
31570 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
31580 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
31590 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
315a0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
315b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
315c0 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
315d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
315e0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
315f0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
31600 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
31610 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
31620 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
31630 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
31640 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
31650 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
31660 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
31670 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
31680 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
31690 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
316a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
316b0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
316c0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
316d0 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
316e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
316f0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
31700 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
31710 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31720 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
31730 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
31740 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31750 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
31760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31770 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31780 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
31790 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
317a0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
317b0 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
317c0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
317d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
317e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
317f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
31800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31810 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
31820 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
31830 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
31840 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
31850 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31860 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
31870 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31880 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
31890 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
318a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
318b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
318c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
318d0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
318e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
318f0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
31900 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
31910 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31920 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
31930 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
31940 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31950 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31960 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
31970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31980 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
319a0 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
319b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
319c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
319d0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
319e0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
319f0 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
31a00 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
31a10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
31a20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
31a30 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
31a40 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
31a50 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
31a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
31a70 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
31a80 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31a90 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
31aa0 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
31ab0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
31ac0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
31ad0 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
31ae0 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
31af0 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
31b00 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
31b10 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
31b20 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
31b30 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
31b40 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
31b50 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
31b60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31b70 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
31b80 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
31b90 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
31ba0 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
31bb0 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
31bc0 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
31bd0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31be0 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
31bf0 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
31c00 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
31c10 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
31c20 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
31c30 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
31c40 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
31c50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
31c60 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
31c70 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
31c80 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
31c90 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
31ca0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
31cb0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31cc0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
31cd0 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
31ce0 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
31cf0 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
31d00 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
31d10 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
31d20 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31d30 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
31d40 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
31d50 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
31d60 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
31d70 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
31d80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31d90 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
31da0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31db0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
31dc0 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
31dd0 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
31de0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
31df0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
31e00 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
31e10 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
31e20 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
31e30 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
31e40 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
31e50 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31e60 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
31e70 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
31e80 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
31e90 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
31ea0 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
31eb0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
31ec0 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
31ed0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
31ee0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31ef0 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
31f00 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
31f10 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
31f20 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
31f30 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
31f40 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
31f50 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
31f60 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
31f70 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
31f80 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
31f90 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
31fa0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31fb0 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
31fc0 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
31fd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31fe0 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
31ff0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
32000 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
32010 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
32020 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
32030 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32040 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
32050 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
32060 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
32070 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
32080 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
32090 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
320a0 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
320b0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
320c0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
320d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
320e0 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
320f0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
32100 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
32110 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
32120 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
32130 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
32140 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
32150 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
32160 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
32170 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
32180 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
32190 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
321a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
321b0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
321c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
321d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
321e0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
321f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
32200 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
32210 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
32220 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
32230 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
32240 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
32250 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
32260 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
32270 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
32280 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
32290 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
322a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
322b0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
322c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
322d0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
322e0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
322f0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
32300 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
32310 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
32320 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
32330 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
32340 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
32350 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
32360 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
32370 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32380 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
32390 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
323a0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
323b0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
323c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
323d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
323e0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
323f0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
32400 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
32410 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
32420 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
32430 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
32440 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
32450 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
32460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32470 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
32480 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
32490 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
324a0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
324b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
324c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
324d0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
324e0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
324f0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
32500 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
32510 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51   function..*/.SQ
32520 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
32530 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
32540 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
32550 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
32560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32570 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
32580 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
32590 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
325a0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
325b0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
325c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
325d0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
325e0 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
325f0 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
32600 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
32610 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
32620 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
32630 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
32640 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
32650 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
32660 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
32670 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
32680 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
32690 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
326a0 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
326b0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
326c0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
326d0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
326e0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
326f0 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
32700 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
32710 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
32720 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
32730 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
32740 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
32750 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
32760 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
32770 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
32780 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
32790 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
327a0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
327b0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
327c0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
327d0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
327e0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
327f0 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
32800 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
32810 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
32820 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
32830 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
32840 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
32850 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32860 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
32870 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32880 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
32890 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
328a0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
328b0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
328c0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
328d0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
328e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
328f0 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
32900 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32910 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65  ction. ^If no me
32920 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
32930 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
32940 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
32950 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
32960 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
32970 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
32980 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
32990 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
329a0 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
329b0 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
329c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
329d0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
329e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
329f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
32a00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32a10 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
32a20 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
32a30 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
32a40 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
32a50 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
32a60 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
32a70 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
32a80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32a90 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32aa0 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
32ab0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
32ac0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
32ad0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
32ae0 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
32af0 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
32b00 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66  estroyed..** ^If
32b10 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
32b20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
32b30 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
32b40 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
32b50 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
32b60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
32b70 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32b80 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
32b90 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
32ba0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
32bb0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
32bc0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
32bd0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
32be0 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
32bf0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
32c00 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
32c10 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
32c20 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
32c30 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
32c40 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
32c50 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
32c60 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
32c70 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79  time.  ^The only
32c80 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
32c90 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
32ca0 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
32cb0 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
32cc0 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
32cd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
32ce0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
32cf0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
32d00 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
32d10 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
32d20 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
32d30 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
32d40 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
32d50 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
32d60 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
32d70 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a  [parameters].)^.
32d80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32d90 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
32da0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
32db0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
32dc0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
32dd0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32de0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
32df0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
32e00 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
32e10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
32e20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  N);.SQLITE_API v
32e30 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
32e40 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
32e50 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
32e60 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
32e70 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
32e80 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
32e90 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
32ea0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
32eb0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
32ec0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
32ed0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
32ee0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
32ef0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
32f00 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
32f10 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
32f20 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
32f30 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
32f40 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
32f50 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
32f60 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
32f70 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
32f80 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
32f90 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
32fa0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
32fb0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
32fc0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
32fd0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
32fe0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
32ff0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
33000 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
33010 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
33020 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
33030 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
33040 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
33050 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
33060 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
33070 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
33080 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
33090 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
330a0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
330b0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
330c0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
330d0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
330e0 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
330f0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
33100 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
33110 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
33120 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
33130 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
33140 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
33150 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
33160 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
33170 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
33180 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
33190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
331a0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
331b0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
331c0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
331d0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
331e0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
331f0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
33200 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
33210 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
33220 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
33230 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
33240 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33250 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
33260 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33270 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
33280 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
33290 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
332a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
332b0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
332c0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
332d0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
332e0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
332f0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
33300 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
33310 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
33320 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
33330 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
33340 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
33350 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
33360 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
33370 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
33380 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33390 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
333a0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
333b0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
333c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
333d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
333e0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
333f0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
33400 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
33410 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
33420 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
33430 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
33440 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
33450 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
33460 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33470 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
33480 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
33490 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
334a0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
334b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
334c0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
334d0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
334e0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
334f0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
33500 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
33510 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
33520 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
33530 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33540 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
33550 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33560 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
33570 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
33580 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33590 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
335a0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
335b0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
335c0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
335d0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
335e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
335f0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33600 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33610 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
33620 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
33630 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
33640 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
33650 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
33660 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
33670 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
33680 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
33690 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
336a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
336b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
336c0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
336d0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
336e0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
336f0 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
33700 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
33710 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
33720 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
33730 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
33740 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
33750 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
33760 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
33770 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33780 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
33790 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
337a0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
337b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
337c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
337d0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
337e0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
337f0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
33800 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
33810 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
33820 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
33830 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
33840 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
33850 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
33860 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
33870 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
33880 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33890 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
338a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
338b0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
338c0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
338d0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
338e0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
338f0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
33900 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
33910 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
33920 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
33930 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33940 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33950 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33960 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
33970 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
33980 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
33990 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
339a0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
339b0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
339c0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
339d0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
339e0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
339f0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
33a00 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
33a10 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
33a20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33a30 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
33a40 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
33a50 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
33a60 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
33a70 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
33a80 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
33a90 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
33aa0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
33ab0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
33ac0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
33ad0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
33ae0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33af0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
33b00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33b10 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
33b20 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
33b30 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
33b40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33b50 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
33b60 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
33b70 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
33b80 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
33b90 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33ba0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
33bb0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
33bc0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
33bd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33be0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
33bf0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
33c00 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
33c10 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
33c20 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33c30 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
33c40 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
33c50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33c60 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
33c70 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33c80 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33c90 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33ca0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33cb0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
33cc0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
33cd0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
33ce0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
33cf0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
33d00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33d10 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
33d20 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
33d30 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
33d40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33d50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33d60 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
33d70 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
33d80 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
33d90 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
33da0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33db0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
33dc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33dd0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
33de0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
33df0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33e00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33e10 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
33e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33e30 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
33e40 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
33e50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
33e60 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
33e70 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33e80 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
33e90 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
33ea0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
33eb0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33ec0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33ed0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
33ee0 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
33ef0 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
33f00 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
33f10 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
33f20 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
33f30 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
33f40 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
33f50 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
33f60 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
33f70 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
33f80 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
33f90 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
33fa0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33fb0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
33fc0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
33fd0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
33fe0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
33ff0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34000 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34010 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
34020 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
34030 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
34040 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
34050 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
34060 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
34070 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
34080 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
34090 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
340a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
340b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
340c0 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
340d0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
340e0 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
340f0 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
34100 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
34110 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
34120 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
34130 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
34140 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
34150 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
34160 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70  t.  If the 3rd p
34170 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
34180 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
34190 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65  t.** must be the
341a0 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74   byte offset int
341b0 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  o the string whe
341c0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
341d0 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61  nator would.** a
341e0 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72  ppear if the str
341f0 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65  ing where NUL te
34200 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
34210 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
34220 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
34230 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74   string at a byt
34240 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73  e offset that is
34250 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76   less than the v
34260 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a  alue of the 3rd.
34270 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ** parameter, th
34280 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
34290 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e   string will con
342a0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
342b0 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65  Ls and the.** re
342c0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
342d0 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e  ons operating on
342e0 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d   strings with em
342f0 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
34300 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66  ndefined..** ^If
34310 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
34320 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
34330 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
34340 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
34350 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
34360 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
34370 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
34380 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
34390 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
343a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
343b0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
343c0 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
343d0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
343e0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
343f0 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
34400 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
34410 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
34420 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34430 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
34440 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34450 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
34460 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
34470 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
34480 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
34490 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
344a0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
344b0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
344c0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
344d0 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
344e0 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
344f0 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
34500 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
34510 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
34520 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
34530 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
34540 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
34550 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
34560 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
34570 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
34580 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
34590 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
345a0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
345b0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
345c0 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
345d0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
345e0 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
345f0 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
34600 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
34610 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
34620 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
34630 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
34640 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34650 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
34660 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
34670 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
34680 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34690 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
346a0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
346b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
346c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
346d0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
346e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
346f0 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
34700 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34710 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
34720 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
34730 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34740 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
34750 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
34760 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
34770 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
34780 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
34790 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
347a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
347b0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
347c0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
347d0 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
347e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
347f0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
34800 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
34810 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
34820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34830 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
34840 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
34850 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
34860 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34870 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
34880 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
34890 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
348a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
348b0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
348c0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
348d0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
348e0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
348f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34900 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34910 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
34920 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
34930 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
34940 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
34950 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
34960 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
34970 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34980 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
34990 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
349a0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
349b0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
349c0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
349d0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
349e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
349f0 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
34a00 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34a10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
34a20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34a30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
34a40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
34a50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34a60 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
34a70 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34a80 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  t void*, int);.S
34a90 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
34aa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34ab0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
34ac0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
34ad0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34ae0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34af0 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
34b00 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
34b10 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
34b20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34b30 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
34b40 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
34b50 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34b60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
34b70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34b80 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
34b90 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34ba0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
34bb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34bc0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
34bd0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34be0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
34bf0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
34c00 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
34c10 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34c20 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
34c30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34c40 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
34c50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34c60 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34c70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34c80 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
34c90 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
34ca0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
34cb0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
34cc0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34cd0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34ce0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
34cf0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
34d00 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
34d10 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
34d20 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34d30 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
34d40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34d50 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
34d60 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
34d70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
34d80 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34d90 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
34da0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
34db0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34dc0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34dd0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
34de0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
34df0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
34e00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
34e10 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
34e20 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
34e30 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
34e40 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
34e50 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
34e60 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
34e70 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
34e80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34e90 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
34ea0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
34eb0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
34ec0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
34ed0 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
34ee0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
34ef0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34f00 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
34f10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34f20 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
34f30 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
34f40 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
34f50 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
34f60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34f70 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
34f80 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
34f90 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
34fa0 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
34fb0 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
34fc0 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
34fd0 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
34fe0 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
34ff0 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
35000 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
35010 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
35020 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
35030 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
35040 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
35050 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
35060 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
35070 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
35080 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
35090 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
350a0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
350b0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
350c0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
350d0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
350e0 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
350f0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
35100 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
35110 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
35120 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
35130 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
35140 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
35150 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
35160 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
35170 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
35180 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
35190 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
351a0 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
351b0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
351c0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
351d0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
351e0 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
351f0 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
35200 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
35210 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
35220 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
35230 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
35240 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
35250 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
35260 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
35270 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
35280 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
35290 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
352a0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
352b0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
352c0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
352d0 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
352e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
352f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35300 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
35310 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35320 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
35330 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
35340 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
35350 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
35360 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
35370 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
35380 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
35390 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
353a0 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
353b0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
353c0 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
353d0 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
353e0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
353f0 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
35400 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35410 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
35420 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
35430 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
35440 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
35450 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
35460 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
35470 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
35480 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
35490 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
354a0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
354b0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
354c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
354d0 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
354e0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
354f0 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
35500 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
35510 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
35520 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
35530 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
35540 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35550 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
35560 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
35570 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
35580 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
35590 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
355a0 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
355b0 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
355c0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
355d0 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
355e0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
355f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35600 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
35610 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
35620 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
35630 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
35640 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
35650 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35660 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
35670 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
35680 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
35690 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
356a0 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
356b0 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
356c0 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
356d0 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
356e0 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
356f0 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
35700 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
35710 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
35720 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
35730 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
35740 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
35750 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
35760 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
35770 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
35780 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
35790 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
357a0 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
357b0 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
357c0 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
357d0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
357e0 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
357f0 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
35800 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
35810 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
35820 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
35830 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
35840 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
35850 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
35860 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
35870 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
35880 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
35890 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
358a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
358b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
358c0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
358d0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
358e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
358f0 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
35900 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
35910 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
35920 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
35930 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
35940 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35950 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
35960 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
35970 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
35980 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
35990 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
359a0 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
359b0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
359c0 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
359d0 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
359e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
359f0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
35a00 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
35a10 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
35a20 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
35a30 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
35a40 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
35a50 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
35a60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35a70 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
35a80 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
35a90 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
35aa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35ab0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35ac0 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
35ad0 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
35ae0 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
35af0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
35b00 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
35b10 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
35b20 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
35b30 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
35b40 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
35b50 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
35b60 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
35b70 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
35b80 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
35b90 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
35ba0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
35bb0 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
35bc0 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
35bd0 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
35be0 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
35bf0 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
35c00 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
35c10 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
35c20 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
35c30 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35c40 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
35c50 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35c60 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ded16()]..*/.SQL
35c70 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35c80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35c90 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
35ca0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
35cb0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
35cc0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
35cd0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
35ce0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
35cf0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
35d00 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
35d10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
35d20 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
35d30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
35d40 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
35d50 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
35d60 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
35d70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
35d80 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
35d90 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
35da0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
35db0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
35dc0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
35dd0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
35de0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
35df0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
35e00 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35e10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
35e20 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
35e30 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
35e40 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
35e50 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
35e60 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
35e70 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
35e80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
35e90 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
35ea0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
35eb0 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
35ec0 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
35ed0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
35ee0 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
35ef0 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
35f00 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
35f10 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
35f20 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
35f30 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
35f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35f50 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
35f60 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
35f70 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
35f80 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
35f90 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
35fa0 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
35fb0 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
35fc0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
35fd0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35fe0 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
35ff0 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
36000 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
36010 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
36020 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
36030 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
36040 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
36050 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
36060 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
36070 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
36080 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
36090 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
360a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
360b0 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
360c0 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
360d0 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
360e0 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
360f0 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
36100 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
36110 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
36120 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
36130 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
36140 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
36150 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
36160 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
36170 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36180 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
36190 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
361a0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
361b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
361c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
361d0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
361e0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
361f0 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
36200 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
36210 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
36220 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
36230 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
36240 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
36250 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
36260 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
36270 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
36280 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
36290 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
362a0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
362b0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
362c0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
362d0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
362e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
362f0 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
36300 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
36310 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
36320 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36330 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
36340 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36350 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
36360 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
36370 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36380 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
36390 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
363a0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
363b0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
363c0 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
363d0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
363e0 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
363f0 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49  t char*).);.SQLI
36400 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36410 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36420 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
36430 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
36440 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
36450 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
36460 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
36470 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
36480 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
36490 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
364a0 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
364b0 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
364c0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
364d0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
364e0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
364f0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
36500 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
36510 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
36520 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
36530 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
36540 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
36550 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
36560 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  PI int sqlite3_k
36570 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
36580 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
36590 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
365a0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
365b0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
365c0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
365d0 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
365e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
365f0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
36600 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
36610 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
36620 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
36630 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
36640 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
36650 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
36660 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
36670 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
36680 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
36690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
366a0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
366b0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
366c0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
366d0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
366e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
366f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
36700 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
36710 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36720 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36730 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
36740 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
36750 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
36760 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
36770 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
36780 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
36790 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
367a0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
367b0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
367c0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
367d0 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
367e0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
367f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
36800 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
36810 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
36820 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
36830 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
36840 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
36850 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
36860 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
36870 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
36880 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
36890 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
368a0 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
368b0 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
368c0 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
368d0 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
368e0 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
368f0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36900 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
36910 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
36920 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
36930 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
36940 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
36950 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
36960 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
36970 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
36980 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
36990 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
369a0 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
369b0 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
369c0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
369d0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
369e0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
369f0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
36a00 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
36a10 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
36a20 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
36a30 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
36a40 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
36a50 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
36a60 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
36a70 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
36a80 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
36a90 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
36aa0 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
36ab0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
36ac0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
36ad0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
36ae0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
36af0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
36b00 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
36b10 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
36b20 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
36b30 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
36b40 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
36b50 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
36b60 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
36b70 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
36b80 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
36b90 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
36ba0 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
36bb0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
36bc0 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
36bd0 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
36be0 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
36bf0 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
36c00 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
36c10 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
36c20 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
36c30 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
36c40 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
36c50 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
36c60 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
36c70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65   int sqlite3_sle
36c80 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
36c90 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
36ca0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
36cb0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
36cc0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
36cd0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
36ce0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
36cf0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
36d00 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
36d10 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
36d20 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
36d30 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
36d40 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
36d50 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
36d60 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
36d70 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
36d80 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
36d90 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
36da0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
36db0 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
36dc0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
36dd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
36de0 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
36df0 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
36e00 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
36e10 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
36e20 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
36e30 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
36e40 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
36e50 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
36e60 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
36e70 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
36e80 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
36e90 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
36ea0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
36eb0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
36ec0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36ed0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
36ee0 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
36ef0 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
36f00 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
36f10 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
36f20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
36f30 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
36f40 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
36f50 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
36f60 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
36f70 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
36f80 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
36f90 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
36fa0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
36fb0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
36fc0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
36fd0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
36fe0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
36ff0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
37000 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
37010 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
37020 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
37030 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
37040 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
37050 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
37060 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
37070 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
37080 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
37090 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
370a0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
370b0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
370c0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
370d0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
370e0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
370f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
37100 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
37110 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
37120 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
37130 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
37140 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
37150 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
37160 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
37170 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
37180 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
37190 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
371a0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
371b0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
371c0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
371d0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
371e0 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
371f0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
37200 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
37210 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
37220 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
37230 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
37240 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
37250 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
37260 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
37270 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
37280 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
37290 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69  3_open] or [sqli
372a0 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f  te3_open_v2].  O
372b0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
372c0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
372d0 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
372e0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
372f0 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20  files may fail. 
37300 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65   Here is an.** e
37310 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f  xample of how to
37320 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43   do this using C
37330 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e 64  ++ with the Wind
37340 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a  ows Runtime:.**.
37350 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
37360 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20  pre>.** LPCWSTR 
37370 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a  zPath = Windows:
37380 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63  :Storage::Applic
37390 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65  ationData::Curre
373a0 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  nt->.** &nbsp;  
373b0 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64     TemporaryFold
373c0 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29  er->Path->Data()
373d0 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42  ;.** char zPathB
373e0 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20  uf&#91;MAX_PATH 
373f0 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d  + 1&#93;;.** mem
37400 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c  set(zPathBuf, 0,
37410 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66   sizeof(zPathBuf
37420 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54  ));.** WideCharT
37430 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54  oMultiByte(CP_UT
37440 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31  F8, 0, zPath, -1
37450 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65  , zPathBuf, size
37460 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a  of(zPathBuf),.**
37470 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c   &nbsp;     NULL
37480 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69  , NULL);.** sqli
37490 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
374a0 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  ry = sqlite3_mpr
374b0 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68  intf("%s", zPath
374c0 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  Buf);.** </pre><
374d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a  /blockquote>.*/.
374e0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
374f0 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
37500 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
37510 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
37520 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
37530 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
37540 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  ng Database File
37550 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
37560 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
37570 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
37580 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
37590 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
375a0 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
375b0 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
375c0 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74  y), then all dat
375d0 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73  abase files.** s
375e0 70 65 63 69 66 69 65 64 20 77 69 74 68 20 61 20  pecified with a 
375f0 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
37600 65 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72  e and created or
37610 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20   accessed by.** 
37620 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
37630 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e  g a built-in win
37640 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66  dows [sqlite3_vf
37650 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65  s | VFS] will be
37660 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62   assumed.** to b
37670 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68  e relative to th
37680 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
37690 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
376a0 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e is a NULL.** p
376b0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
376c0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
376d0 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69   all database fi
376e0 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  les specified.**
376f0 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65   with a relative
37700 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65   pathname are re
37710 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 63 75  lative to the cu
37720 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a  rrent directory.
37730 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65  ** for the proce
37740 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69  ss.  Only the wi
37750 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20  ndows VFS makes 
37760 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62  use of this glob
37770 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20  al.** variable; 
37780 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79  it is ignored by
37790 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a   the unix VFS..*
377a0 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68  *.** Changing th
377b0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  e value of this 
377c0 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61  variable while a
377d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
377e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20  tion is.** open 
377f0 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20  can result in a 
37800 63 6f 72 72 75 70 74 20 64 61 74 61 62 61 73 65  corrupt database
37810 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
37820 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
37830 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
37840 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
37850 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
37860 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
37870 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
37880 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
37890 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
378a0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
378b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
378c0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
378d0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
378e0 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
378f0 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
37900 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
37910 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
37920 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
37930 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
37940 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
37950 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
37960 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
37970 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
37980 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
37990 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
379a0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
379b0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
379c0 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74  ** ^The [data_st
379d0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
379e0 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
379f0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
37a00 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
37a10 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
37a20 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
37a30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37a40 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
37a50 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74  .** the [data_st
37a60 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
37a70 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
37a80 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
37a90 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
37aa0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
37ab0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
37ac0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
37ad0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
37ae0 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
37af0 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
37b00 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
37b10 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
37b20 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
37b30 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
37b40 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
37b50 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
37b60 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
37b70 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
37b80 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
37b90 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
37ba0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
37bb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
37bc0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
37bd0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74   of the [data_st
37be0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
37bf0 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
37c00 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
37c10 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
37c20 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
37c30 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f 72  e3_data_director
37c40 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
37c50 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
37c60 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
37c70 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
37c80 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
37c90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37ca0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
37cb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37cc0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
37cd0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
37ce0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
37cf0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
37d00 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
37d10 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
37d20 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f  ectively.  ^Auto
37d30 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
37d40 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
37d50 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
37d60 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
37d70 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
37d80 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ment..** ^Autoco
37d90 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
37da0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
37db0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
37dc0 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
37dd0 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
37de0 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
37df0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
37e00 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
37e10 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
37e20 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
37e30 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
37e40 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
37e50 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
37e60 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
37e70 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
37e80 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
37e90 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
37ea0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
37eb0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
37ec0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
37ed0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
37ee0 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
37ef0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
37f00 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
37f10 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
37f20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
37f30 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
37f40 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
37f50 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
37f60 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
37f70 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
37f80 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
37f90 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
37fa0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
37fb0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
37fc0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
37fd0 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
37fe0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
37ff0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
38000 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
38010 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
38020 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
38030 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
38040 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
38050 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
38060 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
38070 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
38080 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
38090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
380a0 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
380b0 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
380c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
380d0 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
380e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
380f0 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
38100 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
38110 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
38120 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
38130 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
38140 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
38150 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
38160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
38170 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
38180 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
38190 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
381a0 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
381b0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
381c0 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c  st place..*/.SQL
381d0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
381e0 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
381f0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
38200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38210 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46  EF: Return The F
38220 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61  ilename For A Da
38230 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
38240 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
38250 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
38260 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (D,N) interface 
38270 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
38280 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a  r to a filename.
38290 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
382a0 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66  th database N of
382b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
382c0 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61  ^The main databa
382d0 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74  se file.** has t
382e0 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20  he name "main". 
382f0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
38300 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
38310 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62  e N on the datab
38320 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
38330 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62  n D, or if datab
38340 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f  ase N is a tempo
38350 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72  rary or in-memor
38360 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e  y database, then
38370 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
38380 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
38390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e  **.** ^The filen
383a0 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ame returned by 
383b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
383c0 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74   the output of t
383d0 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e  he.** xFullPathn
383e0 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ame method of th
383f0 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74  e [VFS].  ^In ot
38400 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66  her words, the f
38410 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  ilename.** will 
38420 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  be an absolute p
38430 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66  athname, even if
38440 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73   the filename us
38450 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68  ed.** to open th
38460 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69  e database origi
38470 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20  nally was a URI 
38480 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68  or relative path
38490 6e 61 6d 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  name..*/.SQLITE_
384a0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
384b0 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e  sqlite3_db_filen
384c0 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ame(sqlite3 *db,
384d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
384e0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
384f0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
38500 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
38510 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a  is read-only.**.
38520 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38530 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29  db_readonly(D,N)
38540 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38550 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61  ns 1 if the data
38560 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e  base N.** of con
38570 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61  nection D is rea
38580 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20  d-only, 0 if it 
38590 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f  is read/write, o
385a0 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74  r -1 if N is not
385b0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
385c0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f  a database on co
385d0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53  nnection D..*/.S
385e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
385f0 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
38600 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  y(sqlite3 *db, c
38610 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
38620 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
38630 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
38640 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
38650 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
38660 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
38670 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
38680 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
38690 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
386a0 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
386b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
386c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
386d0 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
386e0 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
386f0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
38700 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
38710 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
38720 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
38730 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
38740 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
38750 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
38760 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
38770 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
38780 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
38790 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
387a0 20 6f 66 20 74 68 69 73 20 72 6f 75 74