System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact c7a0dfb47402ab1166278b5c00c57a86184947aa:


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 35 22 0a 23 64 65 66 69 6e 65 20 53  .7.15".#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 35 0a 23 64 65  MBER 3007015.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 32  CE_ID      "2012
1070: 2d 30 39 2d 31 32 20 30 30 3a 31 31 3a 32 30 20  -09-12 00:11:20 
1080: 39 34 30 32 66 38 31 66 61 64 65 35 66 63 61 65  9402f81fade5fcae
1090: 30 61 33 61 36 65 66 64 63 37 61 35 63 64 66 37  0a3a6efdc7a5cdf7
10a0: 31 66 63 32 65 37 39 66 22 0a 0a 2f 2a 0a 2a 2a  1fc2e79f"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 73  lite3_close() is
2fc0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2fd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fe0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2ff0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3030: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3050: 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  it returns SQLIT
3060: 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61  E_OK but the dea
3070: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3080: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3090: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
30a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30b0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
30c0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
30d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
30e0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
30f0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
3100: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3110: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3120: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3130: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3140: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3150: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3160: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3170: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3180: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3190: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
31a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
31b0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
31c0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
31d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
31e0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
31f0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
3200: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3210: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3230: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3240: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3250: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3260: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3270: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3280: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3290: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
32a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
32b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
32c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
32d0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
32e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
32f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
3300: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3310: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3320: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3330: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3340: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3350: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3360: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3370: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3380: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3390: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
33a0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
33b0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
33c0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
33d0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
33e0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
33f0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
3400: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3410: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3420: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
3430: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3440: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3450: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3460: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3470: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3480: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3490: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
34a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
34c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
34d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
34e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
34f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3500: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3510: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3520: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3530: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3540: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3550: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3560: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3570: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3580: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3590: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
35a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
35b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
35c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
35e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
35f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3600: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3610: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3620: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3630: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3650: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3660: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3670: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3680: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3690: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
36a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
36b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
36c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
36d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
36f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3700: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3710: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3720: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3730: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3740: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3750: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3760: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3770: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3780: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3790: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
37a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
37b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
37c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
37d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
37e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
37f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3800: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3810: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3820: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3830: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3840: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3850: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3860: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3870: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3880: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3890: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
38a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
38b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
38d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
38e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3900: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3910: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3920: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3930: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3940: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3960: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3970: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3980: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3990: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
39a0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
39b0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
39c0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
39d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39e0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39f0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3a00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3a10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3a20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3a30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3a40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3a50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3a60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3a70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3a80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3a90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3aa0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3ab0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3ac0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3ad0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ae0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3af0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3b00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3b10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3b20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3b30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3b40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3b60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3b70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3b80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3b90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3ba0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3bb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3bc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3bd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3be0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3bf0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3c00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3c10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3c20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3c30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3c40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3c50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3c60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3c70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3c80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ca0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3cb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3cc0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3cd0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ce0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3cf0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3d00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3d10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3d20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3d30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3d40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3d50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3d60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3d70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3d80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3d90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3da0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3db0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3dc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3dd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3de0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3df0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3e00: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3e10: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3e20: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3e30: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3e40: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3e50: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3e60: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3e70: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3e80: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3e90: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3ea0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3eb0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3ec0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3ed0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ee0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3ef0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3f00: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3f10: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3f20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f30: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3f40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3f50: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3f60: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3f70: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3f80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3f90: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3fa0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3fb0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3fc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3fd0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3fe0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3ff0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4000: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4010: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4020: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4030: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4040: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
4050: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
4060: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
4070: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40a0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
40b0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
40c0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
40f0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4100: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4110: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4120: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4130: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4140: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4170: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
4180: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
4190: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
41c0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
41d0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
41e0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
41f0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4200: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4220: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4230: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4240: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4250: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
4260: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4270: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4280: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4290: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
42a0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
42b0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
42c0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
42d0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
42e0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
42f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4300: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4310: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4320: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4330: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4340: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4350: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
4360: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
4370: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
4380: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
43a0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
43b0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
43c0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
43d0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
43e0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43f0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4400: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4410: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4420: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4440: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4450: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4460: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4490: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
44a0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
44b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44c0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
44d0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
44e0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44f0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4510: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4520: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4530: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4550: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4560: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4570: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4580: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4590: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
45a0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
45b0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
45c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
45d0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
45e0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45f0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4600: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4620: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4630: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4640: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4650: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4670: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4680: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4690: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
46a0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
46b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
46c0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
46d0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
46e0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4700: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4710: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4720: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4730: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4760: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4770: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4780: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47a0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47b0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
47c0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
47d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
47e0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47f0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4800: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4810: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4830: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4840: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4860: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4870: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4880: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4890: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
48a0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
48b0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
48c0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
48d0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48f0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4900: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4910: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4920: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4930: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4940: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4950: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4970: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4980: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4990: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
49b0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
49c0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
49d0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
49e0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4a00: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4a10: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4a20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4a30: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4a40: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a50: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a60: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a70: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a80: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a90: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4aa0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4ab0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ad0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4ae0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4af0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4b00: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4b10: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4b20: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b30: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b40: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b60: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b70: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b80: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b90: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ba0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4bc0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4bd0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4be0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bf0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4c00: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4c10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4c20: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c50: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c60: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c70: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c80: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c90: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4ca0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4cb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4cc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4cd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4ce0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4d00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4d10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4d20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4da0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4db0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4dc0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4dd0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4de0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4df0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4e00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4e10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4e20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e30: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e50: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e60: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e80: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e90: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4ea0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4eb0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4ec0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ed0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4ee0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ef0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4f00: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4f10: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4f20: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f30: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4f40: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4f50: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4f60: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4f70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4f80: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4f90: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4fa0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4fb0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4fc0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4fd0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4fe0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ff0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
5000: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
5010: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
5020: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5080: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
51e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51f0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5200: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5210: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5230: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5240: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5250: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52d0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5380: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5390: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5540: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5550: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
55b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
55d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
55e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
55f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5600: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5610: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5630: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5650: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5670: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5680: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5690: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
56a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56b0: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
56c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
56d0: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
56e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
56f0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5700: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5710: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
5720: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5730: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
5740: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
5750: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5760: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5770: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5780: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5790: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
57a0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
57b0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
57c0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
57d0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
57e0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
57f0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5800: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5810: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5820: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5830: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5840: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5850: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5870: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
5880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5890: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
58a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
58b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
58c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
58d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58e0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
58f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5900: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5910: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5940: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5950: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5960: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5980: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5990: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
59a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
59b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59c0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
59d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
59e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a00: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5a10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5a20: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5a50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5a60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5a70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a90: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
5aa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5ab0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5ac0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ae0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5af0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5b00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5b30: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5b40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b60: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5b70: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5b80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5bb0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5bc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5be0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5bf0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5c00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c20: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5c30: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5c40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c60: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5c70: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5c80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ca0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5cb0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5cc0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cd0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cf0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5d00: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5d10: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d20: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d40: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5d50: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5d60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d90: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5da0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5db0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5dc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5de0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5df0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
5e00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5e10: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5e30: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5e40: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5e50: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5e60: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5e70: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5e80: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5e90: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5ea0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5eb0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
5ec0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
5ed0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5ee0: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
5ef0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5f00: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5f10: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5f20: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5f30: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5f40: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5f50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5f60: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5f70: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5f80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5f90: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
5fa0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
5fb0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
5fc0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5fd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5fe0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5ff0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6000: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6010: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6020: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6030: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6040: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6050: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6060: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6070: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6080: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6090: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
60a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
60b0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
60c0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
60d0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
60e0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
60f0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6100: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6110: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6120: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6130: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6140: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6150: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6160: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6170: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6180: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6190: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
61a0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
61b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
61c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
61d0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
61e0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
61f0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6200: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6210: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6220: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6230: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6240: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6250: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6260: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6270: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6280: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6290: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
62a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
62b0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
62c0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
62d0: 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  anged..*/.#defin
62e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
62f0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
6300: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
6330: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6340: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
6350: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6360: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
6370: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6390: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
63a0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
63b0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
63c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
63d0: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
63e0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
63f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6400: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
6410: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6420: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
6430: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6440: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
6450: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
6460: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6470: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
6480: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6490: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
64a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
64b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
64c0: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
64d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
64e0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
64f0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6510: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6520: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6530: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6550: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6560: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
6570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6580: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6590: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
65a0: 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  1000../*.** CAPI
65b0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
65c0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
65d0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
65e0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
65f0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6600: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6610: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6620: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6630: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6640: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6650: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6660: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6680: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6690: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
66a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
66b0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
66c0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
66d0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
66e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
66f0: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6700: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6710: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6720: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6730: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6740: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6750: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6760: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6770: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6780: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6790: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
67a0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
67b0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
67c0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
67d0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
67e0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
67f0: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
6800: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6810: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6820: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6830: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6840: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
6850: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
6860: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
6870: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
6880: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
6890: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
68a0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
68b0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
68c0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
68d0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
68e0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
68f0: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
6900: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
6910: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
6920: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
6930: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
6940: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
6950: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
6960: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
6970: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
6980: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
6990: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
69a0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
69b0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
69c0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
69d0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
69e0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
69f0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
6a00: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
6a10: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
6a20: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
6a30: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
6a40: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
6a50: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
6a60: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
6a70: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
6a80: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
6a90: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
6aa0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6ab0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6ac0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
6ad0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
6ae0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
6af0: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
6b00: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
6b10: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
6b20: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
6b30: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
6b40: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
6b50: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
6b60: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
6b70: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
6b80: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
6b90: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
6ba0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
6bb0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6bc0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
6bd0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
6be0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
6bf0: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
6c00: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
6c10: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
6c20: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
6c30: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
6c40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6c50: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
6c60: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
6c70: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6c80: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
6c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ca0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
6cb0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
6cc0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6cd0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
6ce0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
6cf0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
6d00: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
6d10: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
6d20: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
6d30: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
6d40: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
6d50: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
6d60: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
6d70: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
6d80: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
6d90: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
6da0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
6db0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
6dc0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
6dd0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
6de0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
6df0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
6e00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6e10: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
6e20: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
6e30: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
6e40: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
6e50: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
6e60: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
6e70: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
6e80: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
6e90: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
6ea0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
6eb0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
6ec0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
6ed0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
6ee0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
6ef0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
6f00: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6f10: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
6f20: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
6f30: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
6f40: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
6f50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6f60: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
6f70: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
6f80: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6f90: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
6fa0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
6fb0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
6fc0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
6fd0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
6fe0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
6ff0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7000: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7010: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7020: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7030: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7040: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7050: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7060: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7070: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7080: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
7090: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
70a0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
70b0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
70c0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
70d0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
70e0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
70f0: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7100: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7110: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7120: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7130: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7140: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7150: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7160: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7170: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7180: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
7190: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
71a0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
71b0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
71c0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
71d0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
71e0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
71f0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7200: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7210: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7220: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7230: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7240: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7250: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7260: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7270: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7280: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7290: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
72a0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
72b0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
72c0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
72d0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
72e0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
72f0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7300: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7310: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7320: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7330: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7340: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7350: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7360: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7370: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7380: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7390: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
73a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
73b0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
73c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
73d0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
73e0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
73f0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7400: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7410: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7420: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7430: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7440: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7450: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7460: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7470: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7480: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7490: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
74a0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
74b0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
74c0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
74d0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
74e0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
74f0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7500: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7510: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7520: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7530: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7540: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7550: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7560: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7570: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7580: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7590: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
75a0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
75b0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
75c0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
75d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
75e0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
75f0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7600: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7610: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7620: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7630: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7640: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7650: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7660: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7670: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7680: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7690: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
76a0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
76b0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
76c0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
76d0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
76e0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
76f0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7700: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7710: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7720: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7730: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7740: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7750: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7760: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7770: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7780: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7790: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
77a0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
77b0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
77c0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
77d0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
77e0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
77f0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
7800: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
7810: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
7820: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
7830: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
7840: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
7850: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
7860: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
7870: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
7880: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
7890: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
78a0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
78b0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
78c0: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
78d0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
78e0: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
78f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7900: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
7910: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
7920: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
7930: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
7940: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
7950: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
7960: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
7970: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
7980: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
7990: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
79a0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
79b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
79c0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
79d0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
79e0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
79f0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
7a00: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
7a10: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
7a20: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
7a30: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
7a40: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
7a50: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
7a60: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
7a70: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
7a80: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
7a90: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
7aa0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7ab0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
7ac0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7ad0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
7ae0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7af0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
7b00: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7b10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
7b20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7b30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
7b40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7b50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
7b60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7b70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
7b80: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
7ba0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7bb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7bc0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
7bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
7be0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
7bf0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
7c00: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
7c10: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
7c20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7c30: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7c40: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
7c50: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
7c60: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7c80: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
7c90: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
7ca0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
7cb0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
7cc0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
7cd0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
7ce0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
7cf0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
7d00: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
7d10: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
7d20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7d30: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
7d40: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
7d50: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
7d60: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
7d70: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
7d80: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
7d90: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7da0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
7db0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
7dc0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
7dd0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7de0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
7df0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7e00: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
7e10: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
7e20: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
7e30: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
7e40: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
7e50: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
7e60: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
7e70: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
7e80: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
7e90: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
7ea0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
7eb0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
7ec0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
7ed0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
7ee0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
7ef0: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
7f00: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
7f10: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
7f20: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7f30: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
7f40: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
7f50: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
7f60: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
7f70: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7f80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
7f90: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
7fa0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7fb0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
7fc0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
7fd0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
7fe0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7ff0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
8000: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8010: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8020: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8030: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8040: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8050: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8060: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8070: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8080: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8090: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
80a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
80b0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
80c0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
80d0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
80e0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
80f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8100: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8110: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8120: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8130: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8140: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8150: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8160: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
8170: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
8180: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8190: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
81a0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
81b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
81c0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
81d0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
81e0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
81f0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8200: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8210: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8220: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8230: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8240: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8250: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8260: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8270: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8280: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8290: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
82a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
82b0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
82c0: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
82d0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
82e0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
82f0: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8300: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8310: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8320: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8330: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8340: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8350: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8360: 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 2 */.  /* Ad
8370: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8380: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8390: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
83a0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
83b0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
83c0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
83d0: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
83e0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
83f0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
8400: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
8410: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
8420: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
8430: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8440: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8450: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8460: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8470: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
8480: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8490: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
84a0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
84b0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
84c0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
84d0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
84e0: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
84f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8500: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8510: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8520: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8530: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8540: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8550: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
8560: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8570: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
8580: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
8590: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
85a0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
85b0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
85c0: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
85d0: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
85e0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
85f0: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
8600: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
8610: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
8620: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20   is defined..** 
8630: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
8640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8650: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
8660: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8670: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
8680: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
8690: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
86a0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
86b0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
86c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
86d0: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
86e0: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
86f0: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8700: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8710: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8720: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8730: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8740: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8750: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
8760: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
8770: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
8780: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
8790: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
87a0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
87b0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
87c0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
87d0: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
87e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
87f0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8800: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8810: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8820: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
8830: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
8840: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
8850: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
8860: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
8870: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
8880: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
8890: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
88a0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
88b0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
88c0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
88d0: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
88e0: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
88f0: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
8900: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
8910: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
8920: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
8930: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
8940: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
8950: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
8960: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
8970: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
8980: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
8990: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
89a0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
89b0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
89c0: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
89d0: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
89e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
89f0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8a00: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8a10: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8a20: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
8a30: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
8a40: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
8a50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8a60: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
8a70: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
8a80: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
8a90: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
8aa0: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
8ab0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8ac0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
8ad0: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
8ae0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
8af0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8b00: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
8b10: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ED]].** ^(The [S
8b20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8b30: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
8b40: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8b50: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8b60: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
8b70: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
8b80: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
8b90: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
8ba0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
8bb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8bc0: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8bd0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8be0: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8bf0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8c00: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
8c10: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
8c20: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
8c30: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
8c40: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8c50: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8c60: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
8c70: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
8c80: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
8c90: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
8ca0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
8cb0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
8cc0: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8cd0: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8ce0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8cf0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8d00: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
8d10: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
8d20: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
8d30: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
8d40: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
8d50: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
8d60: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
8d70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8d80: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
8d90: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
8da0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
8db0: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
8dc0: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
8dd0: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
8de0: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
8df0: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
8e00: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
8e10: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
8e20: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
8e30: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
8e40: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8e50: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
8e60: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
8e70: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
8e80: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
8e90: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
8ea0: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
8eb0: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
8ec0: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
8ed0: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
8ee0: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
8ef0: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
8f00: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
8f10: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
8f20: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
8f30: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
8f40: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
8f50: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
8f60: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
8f70: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
8f80: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
8f90: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
8fa0: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
8fb0: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
8fc0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
8fd0: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
8fe0: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
8ff0: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
9000: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
9010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
9020: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
9030: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
9040: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
9050: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
9060: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
9070: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
9080: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
9090: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
90a0: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
90b0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
90c0: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
90d0: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
90e0: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
90f0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
9100: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
9110: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
9120: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
9130: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
9140: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9150: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
9160: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
9170: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
9180: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
9190: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
91a0: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
91b0: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
91c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
91d0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
91e0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
91f0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9200: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
9210: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
9220: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
9230: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
9240: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
9250: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
9260: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
9270: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
9280: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
9290: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
92a0: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
92b0: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
92c0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
92d0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
92e0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
92f0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
9300: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
9310: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
9320: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
9330: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
9340: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
9350: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
9360: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
9370: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
9380: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
9390: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
93a0: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
93b0: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
93c0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
93d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
93e0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
93f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9400: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
9410: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
9420: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
9430: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
9440: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
9450: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
9460: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
9470: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
9480: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9490: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
94a0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
94b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
94c0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
94d0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
94e0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
94f0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
9500: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
9510: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
9520: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9530: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9540: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9550: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
9560: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
9570: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
9580: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9590: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
95a0: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
95b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
95c0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
95d0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
95e0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
95f0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9600: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
9610: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
9620: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
9630: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
9640: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
9650: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
9660: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
9670: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
9680: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
9690: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
96a0: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
96b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
96c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
96d0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
96e0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
96f0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9700: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9710: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9720: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
9730: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
9740: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
9750: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
9760: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9770: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9780: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9790: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
97a0: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
97b0: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
97c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
97d0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
97e0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
97f0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9800: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
9810: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
9820: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
9830: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
9840: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
9850: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
9860: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
9870: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
9880: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
9890: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
98a0: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
98b0: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
98c0: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
98d0: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
98e0: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
98f0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
9900: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9910: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
9920: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9930: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
9940: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
9950: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
9960: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
9970: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
9980: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
9990: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
99a0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
99b0: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
99c0: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
99d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
99e0: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
99f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
9a00: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
9a10: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
9a20: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
9a30: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
9a40: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
9a50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9a60: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
9a70: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
9a80: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
9a90: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
9aa0: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
9ab0: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
9ac0: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
9ad0: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
9ae0: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
9af0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
9b00: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
9b10: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
9b20: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
9b30: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
9b40: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
9b50: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
9b60: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9b70: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
9b80: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
9b90: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
9ba0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
9bb0: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
9bc0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9bd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9be0: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
9bf0: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
9c00: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
9c10: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
9c20: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
9c30: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
9c40: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
9c50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
9c60: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
9c70: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
9c80: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
9c90: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
9ca0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
9cb0: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
9cc0: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
9cd0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9ce0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
9cf0: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
9d00: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
9d10: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
9d20: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
9d30: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
9d40: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
9d50: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
9d60: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
9d70: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
9d80: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
9d90: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
9da0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
9db0: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
9dc0: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
9dd0: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
9de0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
9df0: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
9e00: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
9e10: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
9e20: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
9e30: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
9e40: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
9e50: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
9e60: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
9e70: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
9e80: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
9e90: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
9ea0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
9eb0: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
9ec0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
9ed0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
9ee0: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
9ef0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9f00: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
9f10: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
9f20: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
9f30: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
9f40: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
9f50: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
9f60: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
9f70: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
9f80: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
9f90: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
9fa0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
9fb0: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
9fc0: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
9fd0: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
9fe0: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
9ff0: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
a000: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
a010: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  red statement.  
a020: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
a030: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a040: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a050: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
a060: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
a070: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
a080: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a090: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
a0a0: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
a0b0: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
a0c0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
a0d0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
a0e0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
a0f0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
a100: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
a110: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
a120: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a130: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
a140: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
a150: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
a160: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a170: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
a180: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
a190: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
a1a0: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
a1b0: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c  tements..** </ul
a1c0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
a1d0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
a1e0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
a1f0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
a200: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
a210: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
a220: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
a230: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
a240: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
a250: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
a260: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
a270: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
a280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a290: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
a2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
a2b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a2c0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
a2d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
a2e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a2f0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
a300: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
a310: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a320: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
a330: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
a340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a350: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
a360: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
a370: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a380: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
a390: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
a3a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a3b0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
a3c0: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
a3d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
a3e0: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
a3f0: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
a400: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
a410: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a420: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
a430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a440: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
a450: 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41      14../*.** CA
a460: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
a470: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
a480: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
a490: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
a4a0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
a4b0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
a4c0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
a4d0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
a4e0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
a4f0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
a500: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
a510: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
a520: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
a530: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
a540: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
a550: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
a560: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
a570: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
a580: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
a590: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
a5a0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
a5b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
a5c0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
a5d0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
a5e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
a5f0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
a600: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
a610: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
a620: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
a630: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
a640: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
a650: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
a660: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
a670: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
a680: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
a690: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
a6a0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
a6b0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
a6c0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
a6d0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
a6e0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
a6f0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
a700: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
a710: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
a720: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
a730: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
a740: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
a750: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
a760: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
a770: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
a780: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
a790: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
a7a0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
a7b0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
a7c0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
a7d0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
a7e0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
a7f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
a800: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
a810: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
a820: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
a830: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
a840: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
a850: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
a860: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
a870: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
a880: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
a890: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
a8a0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
a8b0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
a8c0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
a8d0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
a8e0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
a8f0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
a900: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
a910: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
a920: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
a930: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
a940: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
a950: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
a960: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
a970: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
a980: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
a990: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
a9a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
a9b0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
a9c0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
a9d0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
a9e0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
a9f0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
aa00: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
aa10: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
aa20: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
aa30: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
aa40: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
aa50: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
aa60: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
aa70: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
aa80: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
aa90: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
aaa0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
aab0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
aac0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
aad0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
aae0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
aaf0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
ab00: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
ab10: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
ab20: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
ab30: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
ab40: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
ab50: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
ab60: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
ab70: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
ab80: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
ab90: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
aba0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
abb0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
abc0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
abd0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
abe0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
abf0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
ac00: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
ac10: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
ac20: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
ac30: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
ac40: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
ac50: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ac60: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
ac70: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
ac80: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
ac90: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
aca0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
acb0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
acc0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
acd0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
ace0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
acf0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
ad00: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
ad10: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
ad20: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
ad30: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
ad40: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
ad50: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
ad60: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
ad70: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
ad80: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
ad90: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
ada0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
adb0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
adc0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
add0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
ade0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
adf0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
ae00: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
ae10: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
ae20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
ae30: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
ae40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
ae50: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
ae60: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
ae70: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
ae80: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
ae90: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
aea0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
aeb0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
aec0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
aed0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
aee0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
aef0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
af00: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
af10: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
af20: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
af30: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
af40: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
af50: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
af60: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
af70: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
af80: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
af90: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
afa0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
afb0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
afc0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
afd0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
afe0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
aff0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
b000: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
b010: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
b020: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
b030: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
b040: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
b050: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
b060: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
b070: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
b080: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
b090: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
b0a0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
b0b0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
b0c0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
b0d0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
b0e0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
b0f0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
b100: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
b110: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
b120: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
b130: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
b140: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
b150: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
b160: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
b170: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
b180: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
b190: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
b1a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
b1b0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
b1c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
b1d0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
b1e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b1f0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
b200: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b210: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
b220: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b230: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
b240: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
b250: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
b260: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
b270: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
b280: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
b290: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b2a0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
b2b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
b2c0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
b2d0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
b2e0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
b2f0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
b300: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
b310: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
b320: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
b330: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
b340: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
b350: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
b360: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
b370: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
b380: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
b390: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
b3a0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
b3b0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
b3c0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
b3d0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
b3e0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
b3f0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
b400: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
b410: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
b420: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
b430: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
b440: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
b450: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
b460: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
b470: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
b480: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
b490: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
b4a0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
b4b0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
b4c0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
b4d0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
b4e0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
b4f0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
b500: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
b510: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
b520: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
b530: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
b540: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
b550: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
b560: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
b570: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b580: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
b590: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
b5a0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
b5b0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
b5c0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
b5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
b5e0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
b5f0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
b600: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
b610: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
b620: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
b630: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
b640: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
b650: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
b660: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
b670: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
b680: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
b690: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
b6a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
b6b0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
b6c0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
b6d0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
b6e0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
b6f0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
b700: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
b710: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
b720: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
b730: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
b740: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
b750: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
b760: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
b770: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
b780: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
b790: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
b7a0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
b7b0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
b7c0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
b7d0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
b7e0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
b7f0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
b800: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
b810: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
b820: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
b830: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
b840: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
b850: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
b860: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
b870: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
b880: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
b890: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
b8a0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
b8b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
b8c0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
b8d0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
b8e0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
b8f0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
b900: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
b910: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
b920: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
b930: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
b940: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
b950: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
b960: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
b970: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b980: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
b990: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
b9a0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
b9b0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
b9c0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
b9d0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
b9e0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
b9f0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
ba00: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
ba10: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
ba20: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
ba30: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
ba40: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
ba50: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
ba60: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
ba70: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
ba80: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
ba90: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
baa0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
bab0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
bac0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
bad0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
bae0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
baf0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
bb00: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
bb10: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
bb20: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
bb30: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
bb40: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
bb50: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
bb60: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
bb70: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
bb80: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
bb90: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
bba0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
bbb0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
bbc0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
bbd0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
bbe0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
bbf0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
bc00: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
bc10: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
bc20: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
bc30: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
bc40: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
bc50: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
bc60: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
bc70: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
bc80: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
bc90: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
bca0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
bcb0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
bcc0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
bcd0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
bce0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
bcf0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
bd00: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
bd10: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
bd20: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
bd30: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
bd40: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
bd50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
bd60: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
bd70: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
bd80: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
bd90: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
bda0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
bdb0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
bdc0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
bdd0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
bde0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
bdf0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
be00: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
be10: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
be20: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
be30: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
be40: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
be50: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
be60: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
be70: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
be80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
be90: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
bea0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
beb0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
bec0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
bed0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
bee0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
bef0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
bf00: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
bf10: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
bf20: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
bf30: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
bf40: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
bf50: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
bf60: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
bf70: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
bf80: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
bf90: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
bfa0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
bfb0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
bfc0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
bfd0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
bfe0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
bff0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
c000: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
c010: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
c020: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
c030: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
c040: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
c050: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
c060: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
c070: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
c080: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
c090: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
c0a0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
c0b0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
c0c0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
c0d0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
c0e0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
c0f0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
c100: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
c110: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
c120: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
c130: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c140: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
c150: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
c160: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
c170: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
c180: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
c190: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
c1a0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
c1b0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
c1c0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
c1d0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
c1e0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
c1f0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
c200: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
c210: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
c220: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
c230: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
c240: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
c250: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
c260: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
c270: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
c280: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
c290: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
c2a0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
c2b0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
c2c0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
c2d0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
c2e0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
c2f0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
c300: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
c310: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
c320: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
c330: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
c340: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
c350: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
c360: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
c370: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
c380: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
c390: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
c3a0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
c3b0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
c3c0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
c3d0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
c3e0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
c3f0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
c400: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
c410: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
c420: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
c430: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
c440: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
c450: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
c460: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
c470: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
c480: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c490: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
c4a0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
c4b0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
c4c0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
c4d0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
c4e0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
c4f0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
c500: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
c510: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
c520: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
c530: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
c540: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
c550: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
c560: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
c570: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
c580: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
c590: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
c5a0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
c5b0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
c5c0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
c5d0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
c5e0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
c5f0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
c600: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
c610: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
c620: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
c630: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
c640: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
c650: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
c660: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
c670: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
c680: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c690: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c6a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
c6b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
c6c0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
c6d0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
c6e0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
c6f0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c700: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
c710: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
c720: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
c730: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c740: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
c750: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
c760: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
c770: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
c780: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c790: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c7a0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
c7b0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
c7c0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
c7d0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
c7e0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
c7f0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
c800: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
c810: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
c820: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
c830: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
c840: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
c850: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
c860: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
c870: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
c880: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
c890: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
c8a0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
c8b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
c8c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
c8d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
c8e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c8f0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
c900: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
c910: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
c920: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
c930: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
c940: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
c950: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
c960: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
c970: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
c980: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
c990: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
c9a0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
c9b0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
c9c0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
c9d0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
c9e0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
c9f0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
ca00: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
ca10: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
ca20: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
ca30: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ca40: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
ca50: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
ca60: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
ca70: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
ca80: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
ca90: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
caa0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
cab0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
cac0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
cad0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
cae0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
caf0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
cb00: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
cb10: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
cb20: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
cb30: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
cb40: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
cb50: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
cb60: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
cb70: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cb80: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
cb90: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
cba0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
cbb0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
cbc0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
cbd0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
cbe0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
cbf0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
cc00: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
cc10: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
cc20: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
cc30: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
cc40: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
cc50: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
cc60: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
cc70: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
cc80: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
cc90: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
cca0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
ccb0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
ccc0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
ccd0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
cce0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
ccf0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
cd00: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
cd10: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
cd20: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
cd30: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
cd40: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
cd50: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
cd60: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
cd70: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
cd80: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
cd90: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
cda0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
cdb0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
cdc0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
cdd0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
cde0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
cdf0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
ce00: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
ce10: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
ce20: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
ce30: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
ce40: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
ce50: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
ce60: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
ce70: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
ce80: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
ce90: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
cea0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
ceb0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
cec0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
ced0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
cee0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
cef0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
cf00: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
cf10: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
cf20: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
cf30: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
cf40: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
cf50: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
cf60: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
cf70: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
cf80: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
cf90: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
cfa0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
cfb0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
cfc0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
cfd0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
cfe0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
cff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d000: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
d010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d020: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
d030: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
d040: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
d050: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
d060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d070: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
d080: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
d090: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d0a0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
d0b0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
d0c0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
d0d0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
d0e0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
d0f0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
d100: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
d110: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
d120: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
d130: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
d140: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
d150: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
d160: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
d170: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
d180: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
d190: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
d1a0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
d1b0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
d1c0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
d1d0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d1e0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
d1f0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
d200: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d210: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
d220: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
d230: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
d240: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
d250: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
d260: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
d270: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
d280: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
d290: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
d2a0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
d2b0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
d2c0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
d2d0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
d2e0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
d2f0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
d300: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
d310: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
d320: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
d330: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
d340: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
d350: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
d360: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
d370: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
d380: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
d390: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
d3a0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
d3b0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
d3c0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
d3d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
d3e0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
d3f0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
d400: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
d410: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
d420: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
d430: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
d440: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
d450: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
d460: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
d470: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
d480: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
d490: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
d4a0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
d4b0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
d4c0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
d4d0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
d4e0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
d4f0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
d500: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
d510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
d520: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
d530: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
d540: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
d550: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
d560: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
d570: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
d580: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
d590: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
d5a0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
d5b0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
d5c0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
d5d0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
d5e0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
d5f0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
d600: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
d610: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
d620: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
d630: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
d640: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
d650: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
d660: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
d670: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
d680: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
d690: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
d6a0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
d6b0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
d6c0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
d6d0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
d6e0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
d6f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d700: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
d710: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
d720: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
d730: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
d740: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
d750: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
d760: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
d770: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
d780: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
d790: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
d7a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
d7b0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
d7c0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
d7d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d7e0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
d7f0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
d800: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
d810: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
d820: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
d830: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
d840: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
d850: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
d860: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
d870: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d880: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
d890: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
d8a0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
d8b0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d8c0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
d8d0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
d8e0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
d8f0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
d900: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
d910: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d920: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
d930: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
d940: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
d950: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
d960: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
d970: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
d980: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
d990: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
d9a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
d9b0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
d9c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
d9d0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
d9e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d9f0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
da00: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
da10: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
da20: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
da30: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
da40: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
da50: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
da60: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
da70: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
da80: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
da90: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
daa0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
dab0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
dac0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
dad0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
dae0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
daf0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
db00: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
db10: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
db20: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
db30: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
db40: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
db50: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
db60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
db70: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
db80: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
db90: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
dba0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
dbb0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
dbc0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
dbd0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
dbe0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
dbf0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
dc00: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
dc10: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
dc20: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
dc30: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
dc40: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
dc50: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
dc60: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
dc70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dc80: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
dc90: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
dca0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
dcb0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
dcc0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
dcd0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
dce0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
dcf0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
dd00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dd10: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
dd20: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
dd30: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
dd40: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
dd50: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
dd60: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
dd70: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
dd80: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
dd90: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
dda0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
ddb0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
ddc0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
ddd0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
dde0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
ddf0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
de00: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
de10: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
de20: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
de30: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
de40: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
de50: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
de60: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
de70: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
de80: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
de90: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
dea0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
deb0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
dec0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
ded0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
dee0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
def0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
df00: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
df10: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
df20: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
df30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
df40: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
df50: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
df60: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
df70: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
df80: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
df90: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
dfa0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
dfb0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
dfc0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
dfd0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
dfe0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
dff0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
e000: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
e010: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
e020: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
e030: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
e040: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e060: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
e070: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
e080: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
e090: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
e0a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
e0b0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
e0c0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
e0d0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
e0e0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
e0f0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
e100: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
e110: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
e120: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
e130: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
e140: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
e150: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
e160: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
e170: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
e180: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
e190: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
e1a0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
e1b0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
e1c0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
e1d0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
e1e0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
e1f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e200: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
e210: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
e220: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
e230: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
e240: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
e250: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
e260: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
e270: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
e280: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
e290: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e2a0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
e2b0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
e2c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e2d0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
e2e0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
e2f0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
e300: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e310: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
e320: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
e330: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
e340: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
e350: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
e360: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
e370: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
e380: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
e390: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
e3a0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
e3b0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
e3c0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
e3d0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
e3e0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
e3f0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
e400: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
e410: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
e420: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
e430: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
e440: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
e450: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
e460: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
e470: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
e480: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
e490: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
e4a0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
e4b0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
e4c0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
e4d0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
e4e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
e4f0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
e500: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
e510: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
e520: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
e530: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
e540: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
e550: 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ilure..*/.SQLITE
e560: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
e570: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
e580: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
e590: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
e5a0: 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
e5b0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
e5c0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
e5d0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
e5e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
e5f0: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
e600: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
e610: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
e620: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
e630: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e640: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
e650: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
e660: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
e670: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
e680: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
e690: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
e6a0: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
e6b0: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
e6c0: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
e6d0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
e6e0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
e6f0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
e700: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
e710: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
e720: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
e730: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
e740: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
e750: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
e760: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
e770: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
e780: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e790: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
e7a0: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
e7b0: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
e7c0: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
e7d0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
e7e0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
e7f0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
e800: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
e810: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
e820: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
e830: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
e840: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
e850: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
e860: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
e870: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
e880: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
e890: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
e8a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
e8b0: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
e8c0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
e8d0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
e8e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e8f0: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
e900: 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
e910: 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
e920: 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
e930: 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
e940: 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
e950: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
e960: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
e970: 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
e980: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
e990: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
e9a0: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
e9b0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
e9c0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
e9d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
e9e0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
e9f0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
ea00: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
ea10: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
ea20: 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
ea30: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
ea40: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
ea50: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
ea60: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
ea70: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
ea80: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
ea90: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
eaa0: 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
eab0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
eac0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
ead0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
eae0: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
eaf0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
eb00: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
eb10: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
eb20: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
eb30: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
eb40: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
eb50: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
eb60: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
eb70: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
eb80: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
eb90: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
eba0: 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  de]..*/.SQLITE_A
ebb0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
ebc0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
ebd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ebe0: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
ebf0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
ec00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
ec10: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
ec20: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
ec30: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
ec40: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
ec50: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
ec60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
ec70: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
ec80: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
ec90: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
eca0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
ecb0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
ecc0: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
ecd0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ece0: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
ecf0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ed00: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
ed10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
ed20: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
ed30: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
ed40: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
ed50: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
ed60: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
ed70: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
ed80: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
ed90: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
eda0: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
edb0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
edc0: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
edd0: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
ede0: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
edf0: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
ee00: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
ee10: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
ee20: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
ee30: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
ee40: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
ee50: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
ee60: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
ee70: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
ee80: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  ccessful..*/.SQL
ee90: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
eea0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
eeb0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
eec0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
eed0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
eee0: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
eef0: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
ef00: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
ef10: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
ef20: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
ef30: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
ef40: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
ef50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
ef60: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
ef70: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
ef80: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
ef90: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
efa0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
efb0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
efc0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
efd0: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
efe0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
eff0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
f000: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
f010: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
f020: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
f030: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
f040: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f050: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
f060: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
f070: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f080: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
f090: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
f0a0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
f0b0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
f0c0: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
f0d0: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
f0e0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
f0f0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
f100: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
f110: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
f120: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
f130: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
f140: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
f150: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
f160: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
f170: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
f180: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
f190: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f1a0: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
f1b0: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
f1c0: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
f1d0: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
f1e0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
f1f0: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
f200: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
f210: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
f220: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
f230: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
f240: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
f250: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f260: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
f270: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
f280: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
f290: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
f2a0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
f2b0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
f2c0: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
f2d0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
f2e0: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
f2f0: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
f300: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
f310: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
f320: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
f330: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
f340: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
f350: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
f360: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
f370: 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
f380: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
f390: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
f3a0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
f3b0: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
f3c0: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
f3d0: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
f3e0: 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
f3f0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
f400: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
f410: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
f420: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
f430: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
f440: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
f450: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
f460: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
f470: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
f480: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
f490: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
f4a0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
f4b0: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
f4c0: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
f4d0: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
f4e0: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
f4f0: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
f500: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
f510: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
f520: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
f530: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
f540: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
f550: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
f560: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
f570: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
f580: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
f590: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
f5a0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
f5b0: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f5c0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
f5d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
f5e0: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
f5f0: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
f600: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
f610: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
f620: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
f630: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
f640: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
f650: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
f660: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
f670: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
f680: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
f690: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
f6a0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
f6b0: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
f6c0: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
f6d0: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
f6e0: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
f6f0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
f700: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
f710: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
f720: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
f730: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
f740: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
f750: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
f760: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
f770: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
f780: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
f790: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
f7a0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
f7b0: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
f7c0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
f7d0: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
f7e0: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
f7f0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
f800: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
f810: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
f820: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
f830: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
f840: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
f850: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
f860: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
f870: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
f880: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
f890: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
f8a0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
f8b0: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
f8c0: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
f8d0: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
f8e0: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
f8f0: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
f900: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
f910: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
f920: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
f930: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
f940: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f950: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
f960: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
f970: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
f980: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
f990: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
f9a0: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
f9b0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
f9c0: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
f9d0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
f9e0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f9f0: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
fa00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
fa10: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
fa20: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
fa30: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
fa40: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
fa50: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
fa60: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
fa70: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
fa80: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
fa90: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
faa0: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
fab0: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
fac0: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
fad0: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
fae0: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
faf0: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
fb00: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
fb10: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
fb20: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
fb30: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
fb40: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
fb50: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
fb60: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
fb70: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
fb80: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fb90: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
fba0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
fbb0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fbc0: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
fbd0: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
fbe0: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
fbf0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
fc00: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
fc10: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
fc20: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
fc30: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
fc40: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
fc50: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
fc60: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
fc70: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
fc80: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
fc90: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
fca0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
fcb0: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
fcc0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
fcd0: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
fce0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
fcf0: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
fd00: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
fd10: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
fd20: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
fd30: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
fd40: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
fd50: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
fd60: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
fd70: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
fd80: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
fd90: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
fda0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
fdb0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
fdc0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
fdd0: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
fde0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
fdf0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
fe00: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
fe10: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
fe20: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
fe30: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
fe40: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
fe50: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
fe60: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
fe70: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
fe80: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
fe90: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
fea0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
feb0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
fec0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
fed0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
fee0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
fef0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
ff00: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
ff10: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
ff20: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
ff30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ff40: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
ff50: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
ff60: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
ff70: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
ff80: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
ff90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ffa0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
ffb0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
ffc0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
ffd0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ffe0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
fff0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10000 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10010 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10020 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10030 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10040 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
10050 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
10060 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
10070 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
10080 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
10090 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
100a0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
100b0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
100c0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
100d0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
100e0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
100f0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10100 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
10110 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
10120 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
10130 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
10140 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
10150 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
10160 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
10170 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
10180 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
10190 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
101a0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
101b0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
101c0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
101d0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
101e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
101f0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
10200 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
10210 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
10220 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
10230 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
10240 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
10250 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
10260 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10270 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
10280 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
10290 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
102a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
102b0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
102c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
102d0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
102e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
102f0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
10300 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10310 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
10320 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10330 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10340 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10350 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
10360 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10370 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
10380 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
10390 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
103a0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
103b0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
103c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
103d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
103e0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
103f0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10400 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
10410 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
10420 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
10430 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10440 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
10450 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
10460 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
10470 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
10480 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
10490 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
104a0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
104b0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
104c0 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
104d0 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
104e0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
104f0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
10500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10510 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
10520 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
10530 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10540 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10550 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10560 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10570 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10580 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
10590 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
105a0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
105b0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
105c0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
105d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
105e0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
105f0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10600 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
10610 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
10620 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
10630 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10640 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
10650 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10660 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
10670 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10680 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
10690 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
106a0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
106b0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
106c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
106d0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
106e0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
106f0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
10700 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
10710 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
10720 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
10730 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
10740 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
10750 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10760 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
10770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
10780 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
10790 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
107a0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
107b0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
107c0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
107d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
107e0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
107f0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
10800 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
10810 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
10820 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10830 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10840 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
10850 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
10860 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
10870 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
10880 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10890 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
108a0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
108b0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
108c0 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
108d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
108e0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
108f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10900 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10910 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10920 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10930 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10940 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10950 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
10960 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
10970 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
10980 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
10990 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
109a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
109b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
109c0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
109d0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
109e0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
109f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
10a00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10a10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10a20 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
10a30 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
10a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10a50 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
10a60 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
10a70 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
10a80 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
10a90 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
10aa0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10ab0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
10ac0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
10ad0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
10ae0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
10af0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10b00 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10b10 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
10b20 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
10b30 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
10b40 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
10b50 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
10b60 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
10b70 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
10b80 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
10b90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
10ba0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
10bb0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
10bc0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10bd0 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
10be0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
10bf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10c00 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
10c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10c20 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
10c30 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10c40 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
10c50 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
10c60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
10c70 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
10c80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
10c90 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
10ca0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
10cb0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
10cc0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
10cd0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
10ce0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
10cf0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
10d00 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
10d10 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
10d20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
10d30 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
10d40 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
10d50 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
10d60 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
10d70 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
10d80 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
10d90 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
10da0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
10db0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
10dc0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
10dd0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10de0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
10df0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10e00 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
10e10 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10e20 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
10e30 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
10e40 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
10e50 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
10e60 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
10e70 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
10e80 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
10e90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10ea0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
10eb0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
10ec0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
10ed0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
10ee0 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
10ef0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
10f00 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
10f10 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
10f20 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
10f30 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
10f40 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
10f50 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
10f60 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
10f70 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
10f80 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
10f90 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
10fa0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
10fb0 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
10fc0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
10fd0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
10fe0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
10ff0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
11000 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
11010 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
11020 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
11030 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
11040 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
11050 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
11060 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
11070 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11080 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
11090 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
110a0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
110b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
110c0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
110d0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
110e0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
110f0 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
11100 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
11110 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
11120 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
11130 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11140 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
11150 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
11160 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
11170 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
11180 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
11190 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
111a0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
111b0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
111c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
111d0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
111e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
111f0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
11200 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
11210 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
11220 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
11230 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
11240 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11250 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
11260 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
11270 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
11280 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
11290 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
112a0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
112b0 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
112c0 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
112d0 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
112e0 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
112f0 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
11300 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
11310 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11320 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
11330 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11340 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
11350 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
11360 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
11370 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
11380 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
11390 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
113a0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
113b0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
113c0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
113d0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
113e0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
113f0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
11400 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11410 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
11420 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
11430 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
11440 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11450 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
11460 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
11470 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
11480 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11490 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
114a0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
114b0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
114c0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
114d0 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
114e0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
114f0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
11500 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11510 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
11520 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
11530 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
11540 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
11550 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
11560 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
11570 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
11580 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
11590 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
115a0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
115b0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
115c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
115d0 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
115e0 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
115f0 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
11600 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
11610 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
11620 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
11630 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
11640 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
11650 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
11660 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
11670 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
11680 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
11690 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
116a0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
116b0 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
116c0 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
116d0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
116e0 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
116f0 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
11700 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
11710 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
11720 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
11730 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
11740 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
11750 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
11760 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
11770 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
11780 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
11790 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
117a0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
117b0 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
117c0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
117d0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
117e0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
117f0 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
11800 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11810 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
11820 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
11830 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
11840 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
11850 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
11860 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
11870 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
11880 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
11890 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
118a0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
118b0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
118c0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
118d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
118e0 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
118f0 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
11900 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
11910 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11920 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
11930 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
11940 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
11950 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
11960 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
11970 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
11980 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
11990 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
119a0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
119b0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
119c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
119d0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
119e0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
119f0 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
11a00 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
11a10 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
11a20 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
11a30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
11a40 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
11a50 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
11a60 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
11a70 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
11a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
11a90 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
11aa0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11ab0 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
11ac0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
11ad0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
11ae0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
11af0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
11b00 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
11b10 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11b20 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
11b30 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
11b40 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
11b50 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
11b60 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
11b70 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
11b80 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
11b90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11ba0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
11bb0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
11bc0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
11bd0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
11be0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
11bf0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11c00 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
11c10 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
11c20 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
11c30 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
11c40 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
11c50 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
11c60 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
11c70 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
11c80 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
11c90 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
11ca0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
11cb0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
11cc0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
11cd0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
11ce0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
11cf0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
11d00 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
11d10 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11d20 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
11d30 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
11d40 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
11d50 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
11d60 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
11d70 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
11d80 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
11d90 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
11da0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
11db0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11dc0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
11dd0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
11de0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
11df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11e00 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
11e10 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
11e20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11e30 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11e40 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
11e50 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
11e60 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
11e70 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
11e80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
11e90 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
11ea0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
11eb0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
11ec0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
11ed0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
11ee0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
11ef0 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
11f00 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
11f10 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
11f20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
11f30 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
11f40 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
11f50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11f60 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
11f70 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
11f80 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11f90 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
11fa0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
11fb0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11fc0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11fd0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11fe0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11ff0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12000 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
12010 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
12020 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
12030 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
12040 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
12050 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
12060 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
12070 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
12080 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
12090 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
120a0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
120b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
120c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
120d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
120e0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
120f0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
12100 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12110 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12120 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12130 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12140 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
12150 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12160 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
12170 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12180 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
12190 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
121a0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
121b0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
121c0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
121d0 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
121e0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
121f0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12200 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12210 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
12220 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12230 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12240 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
12250 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
12260 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
12270 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
12280 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
12290 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
122a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
122b0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
122c0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
122d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
122e0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
122f0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
12300 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
12310 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
12320 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
12330 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
12340 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
12350 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12360 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
12370 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
12380 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12390 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
123a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
123b0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
123c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
123d0 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
123e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
123f0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
12400 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12410 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
12420 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
12430 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
12440 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12450 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
12460 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
12470 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
12480 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
12490 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
124a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
124b0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
124c0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
124d0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
124e0 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
124f0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
12500 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
12510 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
12520 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
12530 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
12540 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
12550 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
12560 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
12570 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12580 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
12590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
125a0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
125b0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
125c0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
125d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
125e0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
125f0 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
12600 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12610 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
12620 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12630 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
12640 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12650 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12660 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12670 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12680 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
12690 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
126a0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
126b0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
126c0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
126d0 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
126e0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
126f0 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
12700 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
12710 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
12720 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
12730 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
12740 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12750 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12770 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
12780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12790 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
127a0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
127b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
127c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
127d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
127e0 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
127f0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
12800 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
12810 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
12820 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
12830 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12840 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
12850 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
12860 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12870 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
12880 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
12890 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
128a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
128b0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
128c0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
128d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
128e0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
128f0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
12900 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
12910 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
12920 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
12930 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
12940 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
12950 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
12960 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
12970 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
12980 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
12990 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
129a0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
129b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
129c0 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
129d0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
129e0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
129f0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
12a00 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
12a10 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
12a20 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12a30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
12a40 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
12a50 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
12a60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
12a70 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
12a80 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
12a90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
12aa0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
12ab0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
12ac0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
12ad0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
12ae0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
12af0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
12b00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12b10 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
12b20 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
12b30 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
12b40 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
12b50 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
12b60 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
12b70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
12b80 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
12b90 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
12ba0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
12bb0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
12bc0 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
12bd0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
12be0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
12bf0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
12c00 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
12c10 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
12c20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
12c30 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
12c40 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
12c50 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
12c60 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
12c70 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
12c80 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
12c90 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
12ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12cb0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
12cc0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
12cd0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
12ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12cf0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
12d00 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12d10 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
12d20 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12d30 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12d40 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
12d50 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
12d60 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
12d70 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
12d80 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
12d90 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
12da0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
12db0 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
12dc0 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
12dd0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
12de0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
12df0 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
12e00 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
12e10 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
12e20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
12e30 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
12e40 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
12e50 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
12e60 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
12e70 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
12e80 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
12e90 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
12ea0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
12eb0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
12ec0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
12ed0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
12ee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
12ef0 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
12f00 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
12f10 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
12f20 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
12f30 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
12f40 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
12f50 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
12f60 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
12f70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
12f80 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
12f90 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
12fa0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
12fb0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
12fc0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
12fd0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
12fe0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
12ff0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
13000 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
13010 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fined..**.** [[S
13020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13030 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
13040 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
13050 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
13060 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
13070 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
13080 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
13090 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
130a0 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
130b0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
130c0 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
130d0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
130e0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
130f0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
13100 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
13110 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  -ops..** </dl>.*
13120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13130 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
13140 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
13150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13160 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
13170 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
13180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13190 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
131a0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
131b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
131c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
131d0 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
131e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
131f0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
13200 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13210 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
13220 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
13230 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
13240 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13250 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
13260 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
13270 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
13280 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13290 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
132a0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
132b0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
132c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
132d0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
132e0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
132f0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
13300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13310 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13320 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
13330 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
13340 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13350 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
13360 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
13370 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
13380 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13390 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
133a0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
133b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
133c0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
133d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
133e0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
133f0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
13400 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
13410 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13420 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
13430 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
13440 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13450 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
13460 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
13470 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13480 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
13490 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
134a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
134b0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
134c0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
134d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
134e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
134f0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
13500 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
13510 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13520 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
13530 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
13540 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
13550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13560 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
13570 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
13580 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
13590 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  2* */../*.** CAP
135a0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
135b0 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
135c0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
135d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
135e0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
135f0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
13600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13610 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
13620 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
13630 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
13640 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13650 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
13660 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
13670 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
13680 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
13690 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
136a0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
136b0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
136c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
136d0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
136e0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
136f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
13700 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
13710 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
13720 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
13730 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
13740 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
13750 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
13760 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
13770 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13780 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
13790 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
137a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
137b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
137c0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
137d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
137e0 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
137f0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
13800 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
13810 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
13820 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
13830 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
13840 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
13850 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
13860 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
13870 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
13880 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
13890 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
138a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
138b0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
138c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
138d0 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
138e0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
138f0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
13900 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
13910 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
13920 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
13930 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
13940 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
13950 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
13960 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
13970 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
13980 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
13990 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
139a0 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
139b0 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
139c0 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
139d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
139e0 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
139f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
13a00 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
13a10 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
13a20 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
13a30 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
13a40 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13a50 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
13a60 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
13a70 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
13a80 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13a90 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
13aa0 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
13ab0 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
13ac0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
13ad0 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
13ae0 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
13af0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
13b00 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
13b10 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
13b20 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
13b30 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
13b40 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
13b50 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
13b60 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
13b70 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
13b80 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
13b90 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
13ba0 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
13bb0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
13bc0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13bd0 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
13be0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
13bf0 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
13c00 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
13c10 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
13c20 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
13c30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
13c40 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
13c50 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
13c60 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
13c70 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
13c80 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
13c90 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
13ca0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
13cb0 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
13cc0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
13cd0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
13ce0 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
13cf0 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
13d00 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
13d10 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
13d20 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
13d30 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
13d40 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
13d50 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
13d60 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
13d70 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
13d80 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
13d90 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
13da0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
13db0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
13dc0 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
13dd0 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
13de0 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
13df0 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
13e00 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
13e10 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
13e20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13e30 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
13e40 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
13e50 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
13e60 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
13e70 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
13e80 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
13e90 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
13ea0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
13eb0 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
13ec0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13ed0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
13ee0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
13ef0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
13f00 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
13f10 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
13f20 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
13f30 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
13f40 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
13f50 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
13f60 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
13f70 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
13f80 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
13f90 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
13fa0 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
13fb0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
13fc0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
13fd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
13fe0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
13ff0 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
14000 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
14010 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
14020 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
14030 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
14040 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
14050 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
14060 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
14070 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
14080 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
14090 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
140a0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
140b0 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
140c0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
140d0 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
140e0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
140f0 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
14100 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
14110 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
14120 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
14130 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
14140 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
14150 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
14160 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
14170 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
14180 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
14190 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
141a0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
141b0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
141c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
141d0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
141e0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
141f0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
14200 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
14210 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
14220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14230 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
14240 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
14250 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
14260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14270 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
14280 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
14290 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
142a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
142b0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
142c0 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
142d0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
142e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
142f0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
14300 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
14310 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
14320 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
14330 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
14340 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
14350 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
14360 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
14370 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
14380 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
14390 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
143a0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
143b0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
143c0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
143d0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
143e0 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ty..*/.SQLITE_AP
143f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
14400 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
14410 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
14420 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
14430 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
14440 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
14450 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
14460 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
14470 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
14480 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
14490 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
144a0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
144b0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
144c0 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
144d0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
144e0 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
144f0 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
14500 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
14510 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
14520 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
14530 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
14540 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
14550 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
14560 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
14570 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
14580 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
14590 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
145a0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
145b0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
145c0 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
145d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
145e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
145f0 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
14600 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
14610 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
14620 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
14630 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
14640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
14650 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
14660 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f  argument.  ^As o
14670 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
14680 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75   3.7.7, this rou
14690 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73  tines.** records
146a0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
146b0 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f   rowid of both o
146c0 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61  rdinary tables a
146d0 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  nd [virtual tabl
146e0 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  es]..** ^If no s
146f0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
14700 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
14710 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
14720 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
14730 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
14740 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
14750 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
14760 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
14770 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
14780 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
14790 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
147a0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
147b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
147c0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
147d0 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
147e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
147f0 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
14800 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
14810 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
14820 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
14830 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
14840 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
14850 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14860 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
14870 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
14880 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
14890 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
148a0 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
148b0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
148c0 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
148d0 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
148e0 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
148f0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
14900 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
14910 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
14920 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
14930 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
14940 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
14950 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
14960 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
14970 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
14980 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
14990 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
149a0 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
149b0 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
149c0 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
149d0 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
149e0 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
149f0 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
14a00 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
14a10 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
14a20 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
14a30 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
14a40 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
14a50 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
14a60 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
14a70 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
14a80 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
14a90 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
14aa0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
14ab0 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
14ac0 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
14ad0 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
14ae0 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
14af0 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
14b00 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
14b10 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
14b20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
14b30 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
14b40 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
14b50 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
14b60 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
14b70 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
14b80 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
14b90 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
14ba0 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
14bb0 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
14bc0 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
14bd0 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
14be0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
14bf0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
14c00 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
14c10 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
14c20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
14c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14c40 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
14c50 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
14c60 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
14c70 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
14c80 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
14c90 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
14ca0 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
14cb0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14cc0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
14cd0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
14ce0 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
14cf0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
14d00 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
14d10 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
14d20 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
14d30 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
14d40 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
14d50 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
14d60 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
14d70 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
14d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14d90 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
14da0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
14db0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
14dc0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
14dd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
14de0 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
14df0 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
14e00 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
14e10 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
14e20 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
14e30 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
14e40 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
14e50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14e60 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
14e70 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
14e80 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
14e90 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
14ea0 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
14eb0 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
14ec0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
14ed0 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
14ee0 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
14ef0 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
14f00 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
14f10 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
14f20 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
14f30 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
14f40 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
14f50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
14f60 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
14f70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
14f80 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
14f90 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
14fa0 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
14fb0 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
14fc0 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
14fd0 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
14fe0 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
14ff0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
15000 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
15010 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
15020 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
15030 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
15040 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
15050 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
15060 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
15070 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
15080 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
15090 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
150a0 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
150b0 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
150c0 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
150d0 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
150e0 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
150f0 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
15100 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
15110 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
15120 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
15130 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
15140 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
15150 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
15160 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
15170 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
15180 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
15190 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
151a0 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
151b0 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
151c0 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
151d0 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
151e0 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
151f0 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
15200 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
15210 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
15220 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
15230 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
15240 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
15250 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
15260 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
15270 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
15280 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
15290 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
152a0 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
152b0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
152c0 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
152d0 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
152e0 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
152f0 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
15300 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
15310 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
15320 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
15330 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
15340 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
15350 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
15360 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
15370 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
15380 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
15390 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
153a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
153b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
153c0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
153d0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
153e0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
153f0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
15400 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
15410 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
15420 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
15430 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
15440 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
15450 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
15460 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
15470 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
15480 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
15490 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
154a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
154b0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
154c0 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
154d0 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
154e0 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
154f0 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
15500 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
15510 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
15520 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
15530 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
15540 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
15550 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
15560 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
15570 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
15580 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
15590 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
155a0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
155b0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
155c0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
155d0 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
155e0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
155f0 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
15600 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
15610 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
15620 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
15630 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
15640 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
15650 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
15660 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
15670 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
15680 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
15690 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
156a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
156b0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
156c0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
156d0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
156e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
156f0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
15700 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
15710 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
15720 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
15730 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
15740 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
15750 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
15760 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
15770 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
15780 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
15790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
157a0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
157b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
157c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
157d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
157e0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
157f0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
15800 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
15810 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
15820 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
15830 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
15840 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
15850 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
15860 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
15870 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
15880 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
15890 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
158a0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
158b0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
158c0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
158d0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
158e0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
158f0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
15900 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
15910 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
15920 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
15930 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
15940 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
15950 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
15960 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
15970 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
15980 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
15990 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
159a0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
159b0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
159c0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
159d0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
159e0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
159f0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
15a00 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
15a10 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
15a20 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
15a30 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
15a40 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
15a50 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
15a60 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
15a70 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
15a80 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
15a90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
15aa0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
15ab0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
15ac0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
15ad0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
15ae0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
15af0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
15b00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
15b10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
15b20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
15b30 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
15b40 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
15b50 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
15b60 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
15b70 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
15b80 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
15b90 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
15ba0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
15bb0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
15bc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15bd0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
15be0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
15bf0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
15c00 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
15c10 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
15c20 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
15c30 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
15c40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
15c50 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
15c60 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
15c70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15c80 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
15c90 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
15ca0 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
15cb0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
15cc0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
15cd0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
15ce0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
15cf0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
15d00 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
15d10 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
15d20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
15d30 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
15d40 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
15d50 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
15d60 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
15d70 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
15d80 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
15d90 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
15da0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
15db0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
15dc0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
15dd0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
15de0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
15df0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
15e00 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
15e10 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
15e20 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
15e30 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
15e40 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
15e50 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
15e60 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
15e70 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
15e80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
15e90 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
15ea0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
15eb0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
15ec0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
15ed0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
15ee0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
15ef0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
15f00 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
15f10 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
15f20 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
15f30 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
15f40 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
15f50 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
15f60 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
15f70 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
15f80 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
15f90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
15fa0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
15fb0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
15fc0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
15fd0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
15fe0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
15ff0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
16000 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
16010 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
16020 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
16030 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
16040 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
16050 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
16060 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
16070 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
16080 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
16090 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
160a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
160b0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
160c0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
160d0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
160e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
160f0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
16100 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
16110 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
16120 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
16130 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
16140 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
16150 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
16160 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
16170 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
16180 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
16190 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
161a0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
161b0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
161c0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
161d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
161e0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
161f0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
16200 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
16210 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
16220 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
16230 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
16240 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
16250 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
16260 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
16270 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
16280 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
16290 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
162a0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
162b0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
162c0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
162d0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
162e0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
162f0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
16300 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
16310 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
16320 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16330 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
16340 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
16350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16360 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
16370 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
16380 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
16390 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
163a0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
163b0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
163c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
163d0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
163e0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
163f0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
16400 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
16410 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
16420 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
16430 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
16440 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
16450 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
16460 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
16470 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
16480 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
16490 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
164a0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
164b0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
164c0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
164d0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
164e0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
164f0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
16500 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
16510 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
16520 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
16530 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
16540 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
16550 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
16560 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
16570 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
16580 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
16590 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
165a0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
165b0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
165c0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
165d0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
165e0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
165f0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
16600 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
16610 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
16620 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
16630 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
16640 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
16650 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
16660 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
16670 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
16680 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
16690 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
166a0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
166b0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
166c0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
166d0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
166e0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
166f0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
16700 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
16710 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
16720 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
16730 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
16740 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
16750 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
16760 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
16770 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
16780 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
16790 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
167a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
167b0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
167c0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
167d0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
167e0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
167f0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
16800 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
16810 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
16820 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
16830 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
16840 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
16850 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
16860 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
16870 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
16880 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
16890 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
168a0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
168b0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
168c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
168d0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
168e0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
168f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
16900 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
16910 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
16920 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
16930 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
16940 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
16950 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
16960 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
16970 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
16980 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
16990 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
169a0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
169b0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
169c0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
169d0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
169e0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
169f0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
16a00 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
16a10 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
16a20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
16a30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
16a40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
16a50 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
16a60 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  sql);.SQLITE_API
16a70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
16a80 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
16a90 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
16aa0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
16ab0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
16ac0 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
16ad0 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
16ae0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
16af0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
16b00 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
16b10 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
16b20 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
16b30 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
16b40 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
16b50 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
16b60 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
16b70 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
16b80 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
16b90 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
16ba0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
16bb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
16bc0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
16bd0 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
16be0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
16bf0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
16c00 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
16c10 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
16c20 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
16c30 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
16c40 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
16c50 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
16c60 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
16c70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
16c80 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
16c90 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
16ca0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
16cb0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
16cc0 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
16cd0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
16ce0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
16cf0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
16d00 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
16d10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
16d20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
16d30 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
16d40 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
16d50 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
16d60 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
16d70 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
16d80 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
16d90 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
16da0 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
16db0 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
16dc0 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
16dd0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
16de0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
16df0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
16e00 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16e10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
16e20 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
16e30 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
16e40 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
16e50 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
16e60 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
16e70 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
16e80 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
16e90 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
16ea0 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
16eb0 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
16ec0 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
16ed0 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
16ee0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
16ef0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
16f00 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
16f10 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
16f20 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
16f30 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
16f40 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
16f50 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
16f60 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
16f70 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
16f80 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
16f90 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
16fa0 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
16fb0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
16fc0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
16fd0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
16fe0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
16ff0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
17000 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
17010 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
17020 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
17030 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
17040 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
17050 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
17060 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
17070 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
17080 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
17090 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
170a0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
170b0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
170c0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
170d0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
170e0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
170f0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
17100 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
17110 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
17120 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
17130 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
17140 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
17150 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
17160 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
17170 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
17180 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
17190 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
171a0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
171b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
171c0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
171d0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
171e0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
171f0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
17200 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
17210 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
17220 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
17230 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
17240 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
17250 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
17260 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
17270 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
17280 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
17290 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
172a0 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
172b0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
172c0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
172d0 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
172e0 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
172f0 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
17300 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
17310 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
17320 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
17330 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
17340 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
17350 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
17360 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
17370 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
17380 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
17390 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
173a0 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
173b0 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
173c0 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
173d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
173e0 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
173f0 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
17400 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
17410 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
17420 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
17430 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
17440 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
17450 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
17460 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
17470 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
17480 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
17490 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
174a0 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
174b0 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
174c0 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
174d0 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
174e0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
174f0 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
17500 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
17510 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
17520 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
17530 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
17540 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
17550 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
17560 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
17570 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
17580 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
17590 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
175a0 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
175b0 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
175c0 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
175d0 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
175e0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
175f0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
17600 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
17610 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
17620 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17630 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
17640 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
17650 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
17660 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
17670 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
17680 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
17690 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
176a0 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
176b0 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
176c0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
176d0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
176e0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
176f0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
17700 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
17710 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
17720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
17730 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17740 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
17750 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
17760 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
17770 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
17780 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
17790 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
177a0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
177b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
177c0 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
177d0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
177e0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
177f0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  andler..*/.SQLIT
17800 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
17810 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
17820 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
17830 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
17840 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17850 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
17860 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
17870 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
17880 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
17890 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
178a0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
178b0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
178c0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
178d0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
178e0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
178f0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
17900 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
17910 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
17920 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
17930 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
17940 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
17950 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
17960 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
17970 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
17980 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
17990 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
179a0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
179b0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
179c0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
179d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
179e0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
179f0 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
17a00 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
17a10 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
17a20 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
17a30 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
17a40 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
17a50 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
17a60 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
17a70 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
17a80 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
17a90 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
17aa0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
17ab0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
17ac0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
17ad0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
17ae0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
17af0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
17b00 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
17b10 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
17b20 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
17b30 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
17b40 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
17b50 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
17b60 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
17b70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73   int sqlite3_bus
17b80 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
17b90 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
17ba0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
17bb0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
17bc0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
17bd0 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
17be0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
17bf0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
17c00 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
17c10 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
17c20 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
17c30 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
17c40 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
17c50 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
17c60 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
17c70 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
17c80 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
17c90 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
17ca0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17cb0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
17cc0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
17cd0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
17ce0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
17cf0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
17d00 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
17d10 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
17d20 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
17d30 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
17d40 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
17d50 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
17d60 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
17d70 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
17d80 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
17d90 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
17da0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
17db0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
17dc0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
17dd0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
17de0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
17df0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
17e00 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
17e10 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
17e20 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
17e30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17e40 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
17e50 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
17e60 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
17e70 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
17e80 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
17e90 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
17ea0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
17eb0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
17ec0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
17ed0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
17ee0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
17ef0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
17f00 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
17f10 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
17f20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
17f30 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
17f40 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
17f50 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
17f60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17f70 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
17f80 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
17f90 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
17fa0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
17fb0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
17fc0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
17fd0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
17fe0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
17ff0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
18000 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
18010 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
18020 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
18030 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
18040 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
18050 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
18060 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
18070 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
18080 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
18090 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
180a0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
180b0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
180c0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
180d0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
180e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
180f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
18100 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
18110 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
18120 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
18130 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
18140 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
18150 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
18160 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
18170 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
18180 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
18190 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
181a0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
181b0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
181c0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
181d0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
181e0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
181f0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
18200 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
18210 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
18220 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
18230 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
18240 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
18250 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
18260 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
18270 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18280 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
18290 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
182a0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
182b0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
182c0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
182d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
182e0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
182f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
18300 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
18310 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
18320 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
18330 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
18340 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
18350 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
18360 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
18370 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
18380 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
18390 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
183a0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
183b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
183c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
183d0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
183e0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
183f0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
18400 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
18410 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
18420 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
18430 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
18440 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
18450 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
18460 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
18470 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
18480 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
18490 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
184a0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
184b0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
184c0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
184d0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
184e0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
184f0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
18500 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
18510 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
18520 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
18530 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
18540 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
18550 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
18560 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
18570 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
18580 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18590 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
185a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
185b0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
185c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
185d0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
185e0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
185f0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
18600 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
18610 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
18620 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
18630 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
18640 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
18650 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
18660 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
18670 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
18680 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
18690 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
186a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
186b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
186c0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
186d0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
186e0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
186f0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
18700 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
18710 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
18720 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
18730 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
18740 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
18750 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
18760 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
18770 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
18780 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
18790 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
187a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
187b0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
187c0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
187d0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
187e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
187f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
18800 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
18810 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
18820 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
18830 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
18840 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
18850 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
18860 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
18870 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
18880 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
18890 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
188a0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
188b0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
188c0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
188d0 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
188e0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
188f0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
18900 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
18910 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
18920 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
18930 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
18940 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
18950 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
18960 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
18970 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
18980 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
18990 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
189a0 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
189b0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
189c0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
189d0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
189e0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
189f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
18a00 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
18a10 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
18a20 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
18a30 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
18a40 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
18a50 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
18a60 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
18a70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
18a80 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
18a90 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
18aa0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
18ab0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
18ac0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
18ad0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
18ae0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
18af0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
18b00 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
18b10 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
18b20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
18b30 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
18b40 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
18b50 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
18b60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
18b70 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
18b80 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
18b90 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
18ba0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
18bb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
18bc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
18bd0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
18be0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
18bf0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
18c00 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
18c10 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
18c20 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
18c30 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
18c40 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
18c50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18c60 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
18c70 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
18c80 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
18c90 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
18ca0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
18cb0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
18cc0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
18cd0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
18ce0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
18cf0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
18d00 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
18d10 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
18d20 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
18d30 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
18d40 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
18d50 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
18d60 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
18d70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
18d80 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
18d90 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
18da0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
18db0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
18dc0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
18dd0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
18de0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
18df0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
18e00 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
18e10 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
18e20 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
18e30 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
18e40 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
18e50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
18e60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
18e70 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
18e80 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
18e90 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
18ea0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
18eb0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
18ec0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
18ed0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
18ee0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
18ef0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
18f00 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
18f10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
18f20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
18f30 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
18f40 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
18f50 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
18f60 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
18f70 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
18f80 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
18f90 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
18fa0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
18fb0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
18fc0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
18fd0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
18fe0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
18ff0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
19000 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
19010 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
19020 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
19030 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
19040 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
19050 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
19060 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
19070 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
19080 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
19090 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
190a0 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
190b0 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
190c0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
190d0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
190e0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
190f0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
19100 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
19110 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
19120 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
19130 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
19140 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
19150 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
19160 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
19170 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
19180 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
19190 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
191a0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
191b0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
191c0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
191d0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
191e0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
191f0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
19200 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
19210 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
19220 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
19230 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
19240 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
19250 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
19260 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
19270 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
19280 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
19290 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
192a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
192b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
192c0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
192d0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
192e0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
192f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
19300 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
19310 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
19320 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
19330 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
19340 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
19350 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
19360 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
19370 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
19380 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
19390 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
193a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
193b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
193c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
193d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
193e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
193f0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
19400 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
19410 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
19420 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
19430 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
19440 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
19450 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
19460 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
19470 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
19480 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
19490 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
194a0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
194b0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
194c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
194d0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
194e0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
194f0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
19500 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
19510 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
19520 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
19530 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
19540 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
19550 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
19560 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
19570 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
19580 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
19590 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
195a0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
195b0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
195c0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
195d0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
195e0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
195f0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
19600 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
19610 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
19620 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
19630 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
19640 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
19650 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
19660 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
19670 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
19680 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
19690 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
196a0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
196b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
196c0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
196d0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
196e0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
196f0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
19700 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
19710 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
19720 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
19730 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
19740 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
19750 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19760 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
19770 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
19780 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
19790 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
197a0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
197b0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
197c0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
197d0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
197e0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
197f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
19800 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
19810 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
19820 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
19830 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
19840 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
19850 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
19860 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
19870 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
19880 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
19890 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
198a0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
198b0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
198c0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
198d0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
198e0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
198f0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
19900 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
19910 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
19920 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
19930 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
19940 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
19950 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
19960 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
19970 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
19980 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
19990 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
199a0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
199b0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
199c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
199d0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
199e0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
199f0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
19a00 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
19a10 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
19a20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
19a30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19a40 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
19a50 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
19a60 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
19a70 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
19a80 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
19a90 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
19aa0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
19ab0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
19ac0 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
19ad0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
19ae0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
19af0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
19b00 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
19b10 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
19b20 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
19b30 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
19b40 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
19b50 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
19b60 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
19b70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19b80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
19b90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
19ba0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
19bb0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
19bc0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
19bd0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
19be0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
19bf0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
19c00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
19c10 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
19c20 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
19c30 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
19c40 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
19c50 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
19c60 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
19c70 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
19c80 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
19c90 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
19ca0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
19cb0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
19cc0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
19cd0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
19ce0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
19cf0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
19d00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
19d10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
19d20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
19d30 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
19d40 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
19d50 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
19d60 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
19d70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
19d80 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
19d90 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
19da0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
19db0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
19dc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
19dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
19de0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
19df0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
19e00 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
19e10 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
19e20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
19e30 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
19e40 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
19e50 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
19e60 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
19e70 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
19e80 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
19e90 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
19ea0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
19eb0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
19ec0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
19ed0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
19ee0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
19ef0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
19f00 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
19f10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
19f20 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
19f30 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
19f40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
19f50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19f60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
19f70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
19f80 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
19f90 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
19fa0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
19fb0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
19fc0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
19fd0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
19fe0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
19ff0 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
1a000 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1a010 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
1a020 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1a030 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
1a040 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1a050 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1a060 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
1a070 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1a080 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1a090 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1a0a0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1a0b0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
1a0c0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1a0d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1a0e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1a0f0 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
1a100 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1a110 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1a120 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1a130 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1a140 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1a150 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1a160 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1a170 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
1a180 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
1a190 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1a1a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1a1b0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1a1c0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
1a1d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1a1e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1a1f0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1a200 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1a210 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
1a220 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
1a230 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
1a240 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1a250 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1a260 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1a270 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1a280 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1a290 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1a2a0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1a2b0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1a2c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1a2d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a2e0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1a2f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1a300 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1a310 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1a320 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
1a330 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1a340 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
1a350 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1a360 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1a370 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1a380 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
1a390 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1a3a0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1a3b0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1a3c0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1a3d0 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1a3e0 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1a3f0 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1a400 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1a410 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1a420 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1a430 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1a440 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1a450 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1a460 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1a470 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1a480 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1a490 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1a4a0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1a4b0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1a4c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1a4d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1a4e0 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1a4f0 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1a500 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1a510 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1a520 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1a530 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1a540 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1a550 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1a560 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1a570 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1a580 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1a590 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1a5a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1a5b0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1a5c0 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1a5d0 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1a5e0 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1a5f0 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1a600 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1a610 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1a620 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1a630 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1a640 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1a650 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1a660 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1a670 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1a680 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1a690 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1a6a0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1a6b0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1a6c0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1a6d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1a6e0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1a6f0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1a700 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1a710 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1a720 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1a730 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1a740 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1a750 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1a760 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1a770 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1a780 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1a790 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1a7a0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1a7b0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1a7c0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1a7d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1a7e0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1a7f0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1a800 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1a810 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1a820 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1a830 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1a840 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1a850 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1a860 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  c()]..*/.SQLITE_
1a870 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1a880 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53  3_malloc(int);.S
1a890 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1a8a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a8b0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
1a8c0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1a8d0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1a8e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a8f0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1a900 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1a910 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1a920 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1a930 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1a940 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1a950 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1a960 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1a970 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1a980 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1a990 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1a9a0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1a9b0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1a9c0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1a9d0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1a9e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1a9f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1aa00 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1aa10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1aa20 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1aa30 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1aa40 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1aa50 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1aa60 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1aa70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1aa80 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1aa90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1aaa0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1aab0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1aac0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1aad0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1aae0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1aaf0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1ab00 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1ab10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1ab20 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1ab30 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1ab40 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1ab50 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1ab60 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1ab70 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1ab80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1ab90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1aba0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1abb0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1abc0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1abd0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1abe0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1abf0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1ac00 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1ac10 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1ac20 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1ac30 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1ac40 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1ac50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1ac60 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1ac70 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1ac80 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1ac90 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1aca0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1acb0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1acc0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1acd0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1ace0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1acf0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1ad00 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1ad10 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51  the reset..*/.SQ
1ad20 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1ad30 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1ad40 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1ad50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1ad60 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1ad70 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1ad80 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1ad90 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1ada0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1adb0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1adc0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1add0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1ade0 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1adf0 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1ae00 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1ae10 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1ae20 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1ae30 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1ae40 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1ae50 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1ae60 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1ae70 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1ae80 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1ae90 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1aea0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1aeb0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1aec0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1aed0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1aee0 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1aef0 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1af00 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1af10 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1af20 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1af30 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1af40 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1af50 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1af60 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1af70 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1af80 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
1af90 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
1afa0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
1afb0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
1afc0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
1afd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
1afe0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
1aff0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1b000 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
1b010 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
1b020 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
1b030 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1b040 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1b050 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
1b060 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
1b070 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
1b080 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1b090 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1b0a0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1b0b0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1b0c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1b0d0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1b0e0 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  thod..*/.SQLITE_
1b0f0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1b100 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1b110 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1b120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1b130 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1b140 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1b150 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
1b160 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1b170 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1b180 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1b190 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1b1a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b1b0 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1b1c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1b1d0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
1b1e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1b1f0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1b200 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1b210 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1b220 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1b230 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1b240 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1b250 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b260 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1b270 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1b280 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1b290 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1b2a0 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1b2b0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
1b2c0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
1b2d0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
1b2e0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
1b2f0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
1b300 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
1b310 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1b320 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
1b330 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
1b340 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
1b350 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
1b360 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
1b370 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
1b380 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
1b390 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
1b3a0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1b3b0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
1b3c0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
1b3d0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
1b3e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1b3f0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
1b400 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
1b410 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
1b420 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
1b430 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1b440 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
1b450 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
1b460 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
1b470 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1b480 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
1b490 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1b4a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
1b4b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
1b4c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
1b4d0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
1b4e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b4f0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1b500 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1b510 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
1b520 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1b530 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1b540 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
1b550 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b560 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1b570 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
1b580 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
1b590 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
1b5a0 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
1b5b0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1b5c0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
1b5d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1b5e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1b5f0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1b600 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
1b610 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
1b620 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1b630 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
1b640 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
1b650 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
1b660 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
1b670 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1b680 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1b690 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1b6a0 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
1b6b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1b6c0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
1b6d0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
1b6e0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
1b6f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
1b700 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1b710 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
1b720 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
1b730 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
1b740 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
1b750 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
1b760 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1b770 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
1b780 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
1b790 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
1b7a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
1b7b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1b7c0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
1b7d0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
1b7e0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
1b7f0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
1b800 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
1b810 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1b820 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1b830 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
1b840 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1b850 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
1b860 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
1b870 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1b880 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
1b890 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
1b8a0 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
1b8b0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
1b8c0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
1b8d0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
1b8e0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
1b8f0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1b900 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1b910 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
1b920 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
1b930 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
1b940 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
1b950 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
1b960 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
1b970 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
1b980 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
1b990 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1b9a0 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
1b9b0 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
1b9c0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1b9d0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1b9e0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
1b9f0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
1ba00 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
1ba10 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
1ba20 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
1ba30 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
1ba40 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
1ba50 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
1ba60 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
1ba70 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
1ba80 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1ba90 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
1baa0 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
1bab0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
1bac0 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
1bad0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
1bae0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
1baf0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
1bb00 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
1bb10 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
1bb20 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
1bb30 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
1bb40 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
1bb50 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
1bb60 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
1bb70 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
1bb80 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
1bb90 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
1bba0 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
1bbb0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
1bbc0 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
1bbd0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
1bbe0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
1bbf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1bc00 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
1bc10 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
1bc20 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
1bc30 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
1bc40 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
1bc50 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
1bc60 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
1bc70 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
1bc80 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
1bc90 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
1bca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1bcb0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
1bcc0 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
1bcd0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
1bce0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
1bcf0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
1bd00 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
1bd10 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
1bd20 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
1bd30 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
1bd40 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
1bd50 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
1bd60 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
1bd70 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1bd80 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
1bd90 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
1bda0 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
1bdb0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1bdc0 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
1bdd0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
1bde0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
1bdf0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
1be00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
1be10 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
1be20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1be30 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
1be40 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
1be50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1be60 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
1be70 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
1be80 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
1be90 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
1bea0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
1beb0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
1bec0 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
1bed0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
1bee0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1bef0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1bf00 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1bf10 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1bf20 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1bf30 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1bf40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1bf50 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
1bf60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
1bf70 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1bf80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1bf90 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1bfa0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1bfb0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1bfc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bfd0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1bfe0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1bff0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1c000 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
1c010 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c020 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
1c030 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
1c040 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
1c050 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
1c060 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
1c070 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1c080 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
1c090 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
1c0a0 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
1c0b0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
1c0c0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
1c0d0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
1c0e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1c0f0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
1c100 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
1c110 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1c120 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
1c130 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c140 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1c150 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
1c160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1c170 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1c180 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
1c190 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
1c1a0 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
1c1b0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
1c1c0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
1c1d0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
1c1e0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
1c1f0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1c200 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
1c210 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
1c220 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1c230 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
1c240 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
1c250 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
1c260 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ange..*/.SQLITE_
1c270 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1c280 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
1c290 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
1c2a0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
1c2b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
1c2c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1c2d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1c2e0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
1c2f0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
1c300 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1c310 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
1c320 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1c330 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1c340 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1c350 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
1c360 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
1c370 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
1c380 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
1c390 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
1c3a0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
1c3b0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
1c3c0 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
1c3d0 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
1c3e0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
1c3f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1c400 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1c410 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
1c420 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
1c430 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1c440 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1c450 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
1c460 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
1c470 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49   used as a [SQLI
1c480 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65  TE_ROLLBACK | re
1c490 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72  turn code].** fr
1c4a0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1c4b0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1c4c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1c4d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c4e0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1c4f0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1c500 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1c510 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1c520 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1c530 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1c540 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1c550 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1c560 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1c570 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1c580 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1c590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1c5a0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1c5b0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1c5c0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1c5d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1c5e0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1c5f0 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1c600 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1c610 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1c620 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1c630 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1c640 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1c650 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1c660 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1c670 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1c680 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1c690 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1c6a0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1c6b0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1c6c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1c6d0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1c6e0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1c6f0 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1c700 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1c710 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1c720 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1c730 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1c740 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1c750 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1c760 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1c770 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1c780 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1c790 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1c7a0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1c7b0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1c7c0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1c7d0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1c7e0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1c7f0 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1c800 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1c810 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1c820 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1c830 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1c840 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1c850 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1c860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c870 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c880 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1c890 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1c8a0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1c8b0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1c8c0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1c8d0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1c8e0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1c8f0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1c900 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1c910 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1c920 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1c930 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c950 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1c960 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1c970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1c980 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1c990 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1c9a0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1c9b0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1c9c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1c9d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1c9e0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1c9f0 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1ca00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ca10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ca20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ca30 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1ca40 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1ca50 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1ca60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ca70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ca80 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1ca90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1caa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1cab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1cac0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1cad0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1cae0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1caf0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1cb00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1cb10 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1cb20 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1cb30 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1cb40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1cb50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1cb60 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1cb70 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1cb80 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1cb90 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1cba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1cbb0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1cbc0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1cbd0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1cbe0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1cbf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cc00 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1cc10 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1cc20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1cc30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1cc40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cc50 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1cc60 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1cc70 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1cc80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1cc90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cca0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1ccb0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1ccc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1ccd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1cce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ccf0 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1cd00 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1cd10 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1cd20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1cd30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cd40 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1cd50 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1cd60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1cd70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cd80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1cd90 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1cda0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1cdb0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1cdc0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1cdd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1cde0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1cdf0 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1ce00 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1ce10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ce20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1ce30 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1ce40 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1ce50 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1ce60 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ce70 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ce80 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1ce90 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1cea0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1ceb0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1cec0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1ced0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1cee0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1cef0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1cf00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1cf10 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1cf20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1cf30 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1cf40 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1cf50 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1cf60 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1cf70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1cf80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1cf90 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1cfa0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1cfb0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1cfc0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1cfd0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1cfe0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1cff0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d000 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
1d010 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
1d020 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1d030 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1d040 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d050 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
1d060 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
1d070 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1d080 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1d090 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d0a0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
1d0b0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
1d0c0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
1d0d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d0e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d0f0 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
1d100 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
1d110 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1d120 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1d130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d140 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
1d150 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
1d160 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1d170 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d180 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d190 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
1d1a0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
1d1b0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
1d1c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1d1d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d1e0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
1d1f0 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
1d200 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1d210 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d230 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
1d240 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
1d250 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1d260 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1d270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1d280 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
1d290 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
1d2a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1d2b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1d2c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
1d2d0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
1d2e0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
1d2f0 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
1d300 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
1d310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
1d320 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
1d330 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
1d340 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
1d350 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
1d360 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
1d370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d380 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
1d390 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
1d3a0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1d3b0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1d3c0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1d3d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1d3e0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1d3f0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1d400 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1d410 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1d420 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1d430 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1d440 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1d450 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1d460 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1d470 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1d480 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1d490 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1d4a0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1d4b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1d4c0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1d4d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1d4e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1d4f0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1d500 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1d510 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1d520 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1d530 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1d540 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1d550 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1d560 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1d570 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1d580 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1d590 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1d5a0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1d5b0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1d5c0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1d5d0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1d5e0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1d5f0 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1d600 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1d610 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1d620 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
1d630 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1d640 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1d650 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1d660 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
1d670 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1d680 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
1d690 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1d6a0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
1d6b0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1d6c0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
1d6d0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1d6e0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
1d6f0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
1d700 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
1d710 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
1d720 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1d730 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
1d740 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
1d750 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
1d760 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
1d770 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
1d780 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
1d790 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
1d7a0 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
1d7b0 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
1d7c0 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
1d7d0 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
1d7e0 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
1d7f0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1d800 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
1d810 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
1d820 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
1d830 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
1d840 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
1d850 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
1d860 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
1d870 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
1d880 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
1d890 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
1d8a0 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
1d8b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
1d8c0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
1d8d0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1d8e0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1d8f0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1d900 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1d910 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
1d920 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1d930 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1d940 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1d950 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1d960 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1d970 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1d980 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1d990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1d9a0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1d9b0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1d9c0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
1d9d0 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
1d9e0 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
1d9f0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
1da00 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
1da10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
1da20 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1da30 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1da40 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
1da50 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1da60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1da70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
1da80 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
1da90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1daa0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
1dab0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1dac0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1dad0 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1dae0 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1daf0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1db00 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
1db10 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
1db20 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
1db30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1db40 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
1db50 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
1db60 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
1db70 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  the number of .*
1db80 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
1db90 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
1dba0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
1dbb0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
1dbc0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
1dbd0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
1dbe0 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e  lback X..**.** ^
1dbf0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
1dc00 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
1dc10 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
1dc20 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
1dc30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dc40 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
1dc50 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
1dc60 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
1dc70 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
1dc80 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
1dc90 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
1dca0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
1dcb0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
1dcc0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1dcd0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
1dce0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
1dcf0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
1dd00 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
1dd10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
1dd20 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
1dd30 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1dd40 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
1dd50 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
1dd60 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
1dd70 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
1dd80 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
1dd90 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
1dda0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
1ddb0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
1ddc0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
1ddd0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
1dde0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1ddf0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1de00 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1de10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1de20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1de30 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1de40 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
1de50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1de60 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1de70 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1de80 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1de90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dea0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1deb0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1dec0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1ded0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54  aph..**.*/.SQLIT
1dee0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1def0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1df00 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1df10 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
1df20 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1df30 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
1df40 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
1df50 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
1df60 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1df70 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1df80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1df90 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
1dfa0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
1dfb0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
1dfc0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1dfd0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1dfe0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1dff0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1e000 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1e010 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1e020 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1e030 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1e040 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1e050 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
1e060 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e070 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1e080 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1e090 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1e0a0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1e0b0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1e0c0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1e0d0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1e0e0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1e0f0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1e100 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1e110 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1e120 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1e130 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1e140 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1e150 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1e160 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
1e170 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1e180 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1e190 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1e1a0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1e1b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1e1c0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1e1d0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1e1e0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1e1f0 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
1e200 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1e210 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1e220 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1e230 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1e240 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1e250 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1e260 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1e270 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
1e280 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
1e290 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
1e2a0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
1e2b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
1e2c0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1e2d0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1e2e0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1e2f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1e300 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1e310 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1e320 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1e330 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1e340 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1e350 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1e360 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1e370 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1e380 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1e390 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1e3a0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1e3b0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1e3c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e3d0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
1e3e0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
1e3f0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
1e400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1e410 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
1e420 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1e430 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1e440 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1e450 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
1e460 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
1e470 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
1e480 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
1e490 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
1e4a0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
1e4b0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
1e4c0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
1e4d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e4e0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
1e4f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1e500 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e510 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
1e520 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1e530 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1e540 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1e550 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1e560 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1e570 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
1e580 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1e590 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1e5a0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
1e5b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1e5c0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
1e5d0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1e5e0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
1e5f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1e600 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1e610 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
1e620 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1e630 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
1e640 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
1e650 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1e660 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
1e670 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
1e680 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1e690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1e6a0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1e6b0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1e6c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1e6d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1e6e0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1e6f0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1e700 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1e710 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1e720 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1e730 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1e740 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1e750 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1e760 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1e770 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1e780 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1e790 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e7a0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1e7b0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1e7c0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
1e7d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1e7e0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
1e7f0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1e800 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1e810 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1e820 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
1e830 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1e840 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1e850 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1e860 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1e870 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1e880 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1e890 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1e8a0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
1e8b0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1e8c0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1e8d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1e8e0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1e8f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1e900 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1e910 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
1e920 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
1e930 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
1e940 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
1e950 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
1e960 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
1e970 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1e980 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1e990 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1e9a0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1e9b0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1e9c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e9d0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1e9e0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1e9f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1ea00 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1ea10 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1ea20 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1ea30 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1ea40 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1ea50 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1ea60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1ea70 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1ea80 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1ea90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1eaa0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1eab0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1eac0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1ead0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1eae0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1eaf0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1eb00 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1eb10 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1eb20 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
1eb30 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1eb40 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1eb50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1eb60 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
1eb70 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
1eb80 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1eb90 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
1eba0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1ebb0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1ebc0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
1ebd0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1ebe0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1ebf0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
1ec00 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1ec10 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1ec20 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1ec30 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
1ec40 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
1ec50 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
1ec60 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
1ec70 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
1ec80 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
1ec90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1eca0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ecb0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1ecc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1ecd0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1ece0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1ecf0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1ed00 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1ed10 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1ed20 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1ed30 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
1ed40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1ed50 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1ed60 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1ed70 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1ed80 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1ed90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1eda0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
1edb0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1edc0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1edd0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
1ede0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
1edf0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
1ee00 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
1ee10 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1ee20 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
1ee30 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
1ee40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1ee50 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
1ee60 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1ee70 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
1ee80 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
1ee90 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
1eea0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
1eeb0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
1eec0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
1eed0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1eee0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
1eef0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
1ef00 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
1ef10 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
1ef20 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
1ef30 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
1ef40 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
1ef50 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
1ef60 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
1ef70 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
1ef80 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1ef90 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
1efa0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1efb0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1efc0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
1efd0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1efe0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
1eff0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
1f000 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
1f010 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
1f020 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
1f030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f040 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
1f050 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
1f060 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
1f070 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
1f080 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
1f090 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
1f0a0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
1f0b0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
1f0c0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
1f0d0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
1f0e0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
1f0f0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
1f100 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
1f110 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
1f120 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
1f130 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1f140 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
1f150 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1f160 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
1f170 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
1f180 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1f190 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
1f1a0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
1f1b0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
1f1c0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
1f1d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
1f1e0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
1f1f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
1f200 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
1f210 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
1f220 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
1f230 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
1f240 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
1f250 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
1f260 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
1f270 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
1f280 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
1f290 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
1f2a0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
1f2b0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
1f2c0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
1f2d0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
1f2e0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
1f2f0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
1f300 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
1f310 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1f320 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
1f330 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
1f340 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
1f350 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
1f360 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
1f370 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
1f380 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
1f390 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
1f3a0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
1f3b0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
1f3c0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
1f3d0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
1f3e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1f3f0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
1f400 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
1f410 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
1f420 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
1f430 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
1f440 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
1f450 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
1f460 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
1f470 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
1f480 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
1f490 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
1f4a0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
1f4b0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
1f4c0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
1f4d0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
1f4e0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
1f4f0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
1f500 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
1f510 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
1f520 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
1f530 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
1f540 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
1f550 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
1f560 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1f570 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
1f580 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
1f590 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
1f5a0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
1f5b0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
1f5c0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
1f5d0 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
1f5e0 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
1f5f0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
1f600 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
1f610 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
1f620 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
1f630 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
1f640 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
1f650 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
1f660 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1f670 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
1f680 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
1f690 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
1f6a0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
1f6b0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
1f6c0 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
1f6d0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1f6e0 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
1f6f0 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
1f700 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
1f710 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
1f720 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1f730 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
1f740 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
1f750 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
1f760 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
1f770 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
1f780 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
1f790 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
1f7a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1f7b0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
1f7c0 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
1f7d0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
1f7e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
1f7f0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
1f800 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
1f810 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
1f820 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
1f830 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
1f840 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
1f850 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
1f860 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
1f870 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
1f880 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1f890 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
1f8a0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
1f8b0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
1f8c0 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
1f8d0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
1f8e0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
1f8f0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
1f900 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
1f910 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
1f920 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1f930 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1f940 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
1f950 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
1f960 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1f970 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1f980 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
1f990 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
1f9a0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
1f9b0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
1f9c0 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
1f9d0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
1f9e0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
1f9f0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
1fa00 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
1fa10 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1fa20 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
1fa30 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
1fa40 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
1fa50 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1fa60 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
1fa70 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
1fa80 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
1fa90 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1faa0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
1fab0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
1fac0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
1fad0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
1fae0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1faf0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
1fb00 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
1fb10 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
1fb20 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
1fb30 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
1fb40 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
1fb50 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
1fb60 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
1fb70 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
1fb80 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
1fb90 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
1fba0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1fbb0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
1fbc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1fbd0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
1fbe0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
1fbf0 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
1fc00 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
1fc10 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1fc20 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
1fc30 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
1fc40 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
1fc50 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
1fc60 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
1fc70 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
1fc80 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
1fc90 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
1fca0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
1fcb0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
1fcc0 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
1fcd0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
1fce0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
1fcf0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1fd00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1fd10 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
1fd20 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
1fd30 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
1fd40 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
1fd50 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
1fd60 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
1fd70 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
1fd80 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
1fd90 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1fda0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
1fdb0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1fdc0 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
1fdd0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
1fde0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
1fdf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1fe00 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
1fe10 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
1fe20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
1fe30 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
1fe40 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
1fe50 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
1fe60 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
1fe70 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
1fe80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1fe90 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
1fea0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
1feb0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
1fec0 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
1fed0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
1fee0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
1fef0 76 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20  viour requested 
1ff00 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
1ff10 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
1ff20 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
1ff30 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1ff40 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c  CACHE flag..** <
1ff50 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
1ff60 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
1ff70 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
1ff80 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1ff90 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
1ffa0 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
1ffb0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1ffc0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1ffd0 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
1ffe0 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
1fff0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
20000 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
20010 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
20020 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
20030 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
20040 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
20050 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
20060 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
20070 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
20080 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
20090 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
200a0 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
200b0 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
200c0 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
200d0 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
200e0 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
200f0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
20100 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
20110 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
20120 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
20130 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
20140 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
20150 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
20160 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
20170 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
20180 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
20190 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
201a0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
201b0 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
201c0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
201d0 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
201e0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
201f0 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
20200 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
20210 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
20220 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
20230 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
20240 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
20250 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
20260 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
20270 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
20280 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
20290 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
202a0 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
202b0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
202c0 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
202d0 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
202e0 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
202f0 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
20300 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
20310 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
20320 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
20330 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
20340 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
20350 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
20360 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
20370 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
20380 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
20390 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
203a0 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
203b0 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
203c0 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
203d0 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
203e0 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
203f0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
20400 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
20410 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
20420 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
20430 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
20440 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
20450 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
20460 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
20470 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
20480 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
20490 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
204a0 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
204b0 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
204c0 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
204d0 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
204e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
204f0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
20500 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
20510 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
20520 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
20530 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
20540 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
20550 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
20560 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
20570 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
20580 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
20590 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
205a0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
205b0 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
205c0 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
205d0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
205e0 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
205f0 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
20600 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
20610 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
20620 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
20630 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
20640 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
20650 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
20660 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
20670 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
20680 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
20690 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
206a0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
206b0 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
206c0 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
206d0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
206e0 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
206f0 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
20700 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
20710 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
20720 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
20730 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
20740 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
20750 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
20760 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
20770 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
20780 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
20790 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
207a0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
207b0 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
207c0 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
207d0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
207e0 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
207f0 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
20800 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
20810 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
20820 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
20830 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
20840 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
20850 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
20860 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
20870 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
20880 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20890 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
208a0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
208b0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
208c0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
208d0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
208e0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
208f0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
20900 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
20910 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
20920 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
20930 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
20940 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
20950 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
20960 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
20970 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
20980 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
20990 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
209a0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
209b0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
209c0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
209d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
209e0 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
209f0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
20a00 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
20a10 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
20a20 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
20a30 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
20a40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
20a50 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
20a60 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ry].*/.SQLITE_AP
20a70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
20a80 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
20a90 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
20aa0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
20ab0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
20ac0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
20ad0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
20ae0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
20af0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
20b00 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
20b10 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
20b20 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
20b30 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
20b40 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
20b50 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
20b60 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
20b70 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
20b80 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
20b90 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
20ba0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
20bb0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
20bc0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
20bd0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
20be0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
20bf0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
20c00 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
20c10 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
20c20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
20c30 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
20c40 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
20c50 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
20c60 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
20c70 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
20c80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
20c90 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
20ca0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
20cb0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
20cc0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
20cd0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
20ce0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
20cf0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
20d00 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
20d10 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
20d20 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
20d30 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
20d40 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
20d50 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
20d60 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
20d70 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
20d80 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
20d90 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
20da0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
20db0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
20dc0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
20dd0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
20de0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
20df0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
20e00 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
20e10 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
20e20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
20e30 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
20e40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
20e50 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
20e60 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
20e70 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
20e80 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
20e90 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
20ea0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
20eb0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
20ec0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
20ed0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
20ee0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
20ef0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
20f00 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
20f10 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
20f20 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
20f30 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
20f40 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
20f50 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
20f60 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
20f70 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
20f80 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
20f90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
20fa0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
20fb0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
20fc0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
20fd0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
20fe0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
20ff0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
21000 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
21010 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
21020 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
21030 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
21040 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
21050 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
21060 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
21070 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
21080 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
21090 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
210a0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
210b0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
210c0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
210d0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
210e0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
210f0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
21100 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
21110 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
21120 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
21130 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
21140 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
21150 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
21160 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
21170 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
21180 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
21190 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
211a0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
211b0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
211c0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
211d0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
211e0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
211f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
21200 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
21210 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
21220 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
21230 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
21240 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
21250 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
21260 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
21270 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
21280 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
21290 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
212a0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
212b0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
212c0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
212d0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
212e0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
212f0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
21300 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
21310 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
21320 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
21330 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
21340 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
21350 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
21360 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
21370 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
21380 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
21390 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
213a0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
213b0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
213c0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
213d0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
213e0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
213f0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
21400 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
21410 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
21420 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
21430 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
21440 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
21450 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
21460 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
21470 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
21480 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
21490 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
214a0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
214b0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
214c0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
214d0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53  char *zParam);.S
214e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
214f0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21500 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
21510 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
21520 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
21530 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41  fault);.SQLITE_A
21540 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
21550 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
21560 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
21570 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
21580 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
21590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
215a0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
215b0 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  essages.**.** ^T
215c0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
215d0 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
215e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
215f0 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
21600 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
21610 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
21620 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
21630 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
21640 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
21650 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
21660 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21670 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
21680 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
21690 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
216a0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
216b0 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
216c0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
216d0 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
216e0 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
216f0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  fined.  ^The sql
21700 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
21710 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
21720 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
21730 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
21740 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
21750 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
21760 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
21770 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
21780 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
21790 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
217a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
217b0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
217c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
217d0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
217e0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
217f0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
21800 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
21810 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
21820 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
21830 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
21840 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
21850 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
21860 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
21870 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
21880 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
21890 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
218a0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
218b0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
218c0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
218d0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
218e0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
218f0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
21900 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
21910 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
21920 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
21930 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
21940 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
21950 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
21960 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
21970 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
21980 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
21990 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
219a0 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
219b0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
219c0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
219d0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
219e0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
219f0 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
21a00 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
21a10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21a20 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
21a30 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
21a40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
21a50 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
21a60 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
21a70 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
21a80 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
21a90 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
21aa0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
21ab0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
21ac0 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
21ad0 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
21ae0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
21af0 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
21b00 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
21b10 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
21b20 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
21b30 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
21b40 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
21b50 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
21b60 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
21b70 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
21b80 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
21b90 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
21ba0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
21bb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
21bc0 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
21bd0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
21be0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
21bf0 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
21c00 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
21c10 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
21c20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
21c30 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
21c40 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
21c50 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
21c60 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
21c70 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
21c80 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
21c90 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
21ca0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
21cb0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
21cc0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
21cd0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
21ce0 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
21cf0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
21d00 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
21d10 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
21d20 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
21d30 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
21d40 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53  not be set..*/.S
21d50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
21d60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
21d70 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
21d80 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
21d90 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
21da0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
21db0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
21dc0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
21dd0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
21de0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
21df0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21e00 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
21e10 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  e3*);.SQLITE_API
21e20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
21e30 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
21e40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21e50 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
21e60 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
21e70 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
21e80 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
21e90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
21ea0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
21eb0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
21ec0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
21ed0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
21ee0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
21ef0 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
21f00 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
21f10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
21f20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
21f30 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
21f40 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
21f50 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
21f60 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
21f70 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
21f80 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
21f90 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
21fa0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
21fb0 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
21fc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21fd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
21fe0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
21ff0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
22000 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
22010 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
22020 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
22030 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
22040 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
22050 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
22060 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
22070 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
22080 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
22090 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
220a0 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
220b0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
220c0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
220d0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
220e0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
220f0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
22100 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
22110 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
22120 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
22130 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
22140 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
22150 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
22160 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
22170 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
22180 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
22190 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
221a0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
221b0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
221c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
221d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
221e0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
221f0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
22200 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
22210 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
22220 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
22230 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
22240 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
22250 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
22260 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
22270 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
22280 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
22290 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
222a0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
222b0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
222c0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
222d0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
222e0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
222f0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
22300 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
22310 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
22320 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
22330 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
22340 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
22350 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
22360 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
22370 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
22380 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
22390 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
223a0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
223b0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
223c0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
223d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
223e0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
223f0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
22400 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
22410 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
22420 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
22430 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
22440 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
22450 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
22460 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
22470 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
22480 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
22490 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
224a0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
224b0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
224c0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
224d0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
224e0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
224f0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
22500 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
22510 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
22520 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
22530 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
22540 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
22550 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
22560 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
22570 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
22580 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
22590 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
225a0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
225b0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
225c0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
225d0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
225e0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
225f0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
22600 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
22610 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
22620 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
22630 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
22640 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
22650 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
22660 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
22670 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
22680 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
22690 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
226a0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
226b0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
226c0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
226d0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
226e0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
226f0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
22700 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
22710 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
22720 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
22730 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
22740 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
22750 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
22760 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
22770 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
22780 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
22790 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
227a0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
227b0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
227c0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
227d0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
227e0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
227f0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
22800 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
22810 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
22820 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
22830 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
22840 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
22850 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
22860 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
22870 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
22880 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
22890 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
228a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
228b0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
228c0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
228d0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
228e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
228f0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
22900 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
22910 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
22920 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
22930 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
22940 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
22950 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
22960 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
22970 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
22980 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49  eleases..*/.SQLI
22990 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
229a0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
229b0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
229c0 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
229d0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
229e0 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
229f0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
22a00 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
22a10 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
22a20 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
22a30 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
22a40 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
22a50 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
22a60 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
22a70 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
22a80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
22a90 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
22aa0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
22ab0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
22ac0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
22ad0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
22ae0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
22af0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
22b00 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
22b10 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
22b20 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
22b30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22b40 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
22b50 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
22b60 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
22b70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
22b80 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
22b90 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
22ba0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
22bb0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
22bc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
22bd0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
22be0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
22bf0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
22c00 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
22c10 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
22c20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
22c30 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
22c40 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
22c50 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
22c60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
22c70 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
22c80 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
22c90 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
22ca0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
22cb0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
22cc0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
22cd0 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
22ce0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22cf0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
22d00 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
22d10 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
22d20 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
22d30 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22d40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
22d50 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
22d60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
22d70 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
22d80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
22d90 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
22da0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
22db0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
22dc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22dd0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
22de0 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
22df0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
22e00 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
22e10 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22e20 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
22e30 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
22e40 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
22e50 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
22e60 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
22e70 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
22e80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
22e90 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
22ea0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
22eb0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
22ec0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
22ed0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
22ee0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
22ef0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
22f00 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
22f10 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
22f20 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
22f30 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
22f40 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
22f50 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
22f60 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
22f70 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22f80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
22f90 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
22fa0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
22fb0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
22fc0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
22fd0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
22fe0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
22ff0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
23000 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23010 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
23020 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23030 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
23040 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23050 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
23060 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
23070 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
23080 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
23090 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
230a0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
230b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
230c0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
230d0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
230e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
230f0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
23100 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
23110 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
23120 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
23130 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
23140 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23150 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
23160 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
23170 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
23180 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
23190 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
231a0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
231b0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
231c0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
231d0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
231e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
231f0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
23200 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
23210 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
23220 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
23230 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
23240 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
23250 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
23260 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
23270 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
23280 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
23290 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
232a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
232b0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
232c0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
232d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
232e0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
232f0 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
23300 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23310 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
23320 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
23330 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23340 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
23350 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
23360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
23370 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
23380 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
23390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
233a0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
233b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
233c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
233d0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
233e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
233f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23400 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
23410 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
23420 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
23430 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
23440 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
23450 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
23460 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
23470 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
23480 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
23490 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
234a0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
234b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
234c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
234d0 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
234e0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
234f0 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
23500 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
23510 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
23520 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
23530 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
23540 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
23550 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23560 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
23570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23580 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
23590 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
235a0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
235b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
235c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
235d0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
235e0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
235f0 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
23600 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
23610 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
23620 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
23630 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
23640 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
23650 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
23660 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
23670 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
23680 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
23690 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
236a0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
236b0 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
236c0 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
236d0 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
236e0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
236f0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
23700 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
23710 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
23720 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
23730 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
23740 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
23750 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
23760 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
23770 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
23780 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
23790 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
237a0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
237b0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
237c0 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
237d0 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
237e0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
237f0 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
23800 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
23810 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
23820 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
23830 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
23840 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
23850 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
23860 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
23870 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
23880 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
23890 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
238a0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
238b0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
238c0 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
238d0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
238e0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
238f0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
23900 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
23910 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
23920 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
23930 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
23940 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
23950 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
23960 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
23970 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53   as this saves S
23980 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e  QLite from havin
23990 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63  g to.** make a c
239a0 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74  opy of the input
239b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
239c0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
239d0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
239e0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
239f0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
23a00 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
23a10 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
23a20 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
23a30 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
23a40 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
23a50 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
23a60 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
23a70 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
23a80 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
23a90 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
23aa0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
23ab0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
23ac0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
23ad0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
23ae0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23af0 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
23b00 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
23b10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
23b20 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
23b30 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
23b40 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
23b50 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
23b60 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
23b70 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
23b80 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
23b90 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
23ba0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
23bb0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
23bc0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
23bd0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
23be0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
23bf0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
23c00 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
23c10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
23c20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
23c30 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
23c40 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
23c50 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
23c60 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
23c70 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
23c80 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
23c90 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
23ca0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
23cb0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
23cc0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
23cd0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
23ce0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
23cf0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
23d00 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
23d10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23d20 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
23d30 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
23d40 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
23d50 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
23d60 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
23d70 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
23d80 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
23d90 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
23da0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
23db0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
23dc0 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
23dd0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
23de0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23df0 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
23e00 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
23e10 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
23e20 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
23e30 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
23e40 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
23e50 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
23e60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23e70 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
23e80 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
23e90 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
23ea0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
23eb0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
23ec0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
23ed0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
23ee0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
23ef0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
23f00 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
23f10 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
23f20 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
23f30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
23f40 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
23f50 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
23f60 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
23f70 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  gain..** </li>.*
23f80 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
23f90 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
23fa0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
23fb0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
23fc0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
23fd0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
23fe0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
23ff0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
24000 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
24010 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
24020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
24030 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
24040 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
24050 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
24060 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
24070 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
24080 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
24090 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
240a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
240b0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
240c0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
240d0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
240e0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
240f0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
24100 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
24110 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
24120 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
24130 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
24140 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
24150 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
24160 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
24170 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
24180 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
24190 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
241a0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
241b0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
241c0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
241d0 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
241e0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
241f0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
24200 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
24210 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
24220 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
24230 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
24240 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
24250 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
24260 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
24270 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
24280 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
24290 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
242a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
242b0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
242c0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
242d0 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
242e0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
242f0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
24300 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
24310 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
24320 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
24330 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
24340 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
24350 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
24360 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
24370 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
24380 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
24390 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
243a0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
243b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
243c0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
243d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
243e0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
243f0 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c  ..** the .** </l
24400 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53  i>.** </ol>.*/.S
24410 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24420 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
24430 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
24440 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
24450 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
24460 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
24470 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
24480 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
24490 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
244a0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
244b0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
244c0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
244d0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
244e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
244f0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
24500 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
24510 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
24520 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
24530 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
24540 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
24550 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
24560 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
24570 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
24580 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
24590 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
245a0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
245b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
245c0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
245d0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
245e0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
245f0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
24600 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
24610 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
24620 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
24630 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
24640 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
24650 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
24660 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
24670 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
24680 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
24690 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
246a0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
246b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
246c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
246d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
246e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
246f0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
24700 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
24710 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
24720 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
24730 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
24740 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
24750 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
24760 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
24770 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
24780 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
24790 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
247a0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
247b0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
247c0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
247d0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
247e0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
247f0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53   of zSql */.);.S
24800 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
24820 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
24830 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
24840 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
24850 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
24860 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
24870 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
24880 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
24890 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
248a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
248b0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
248c0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
248d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
248e0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
248f0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
24900 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
24910 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
24920 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
24930 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
24940 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
24950 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24960 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
24970 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
24980 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
24990 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
249a0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
249b0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
249c0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
249d0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
249e0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
249f0 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
24a00 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
24a10 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
24a20 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
24a30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
24a40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
24a50 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
24a60 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
24a70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
24a80 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
24a90 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
24aa0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
24ab0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
24ac0 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
24ad0 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a  he Database.**.*
24ae0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
24af0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
24b00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24b10 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
24b20 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
24b30 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
24b40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
24b50 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
24b60 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
24b70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
24b80 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
24b90 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
24ba0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
24bb0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
24bc0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
24bd0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
24be0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
24bf0 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
24c00 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
24c10 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
24c20 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
24c30 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
24c40 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
24c50 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
24c60 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
24c70 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
24c80 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
24c90 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
24ca0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
24cb0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
24cc0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
24cd0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
24ce0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
24cf0 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
24d00 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
24d10 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
24d20 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
24d30 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
24d40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
24d50 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
24d60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
24d70 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
24d80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
24d90 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
24da0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
24db0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
24dc0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
24dd0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
24de0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
24df0 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
24e00 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
24e10 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
24e20 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
24e30 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
24e40 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
24e50 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
24e60 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
24e70 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
24e80 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
24e90 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
24ea0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
24eb0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
24ec0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
24ed0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
24ee0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
24ef0 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
24f00 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
24f10 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
24f20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
24f30 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
24f40 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
24f50 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
24f60 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
24f70 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
24f80 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
24f90 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
24fa0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
24fb0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
24fc0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
24fd0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
24fe0 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   disk..*/.SQLITE
24ff0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
25000 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
25010 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
25020 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
25030 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
25040 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
25050 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
25060 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68   Reset.**.** ^Th
25070 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
25080 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
25090 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
250a0 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
250b0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
250c0 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
250d0 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
250e0 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
250f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
25100 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74  (S)] but has not
25110 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
25120 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f  on and/or has no
25130 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  t .** been reset
25140 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25150 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
25160 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
25170 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
25180 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
25190 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
251a0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
251b0 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
251c0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
251d0 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
251e0 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
251f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
25200 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
25210 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
25220 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
25230 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
25240 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
25250 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
25260 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
25270 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
25280 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
25290 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
252a0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
252b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
252c0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
252d0 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
252e0 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
252f0 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
25300 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
25310 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
25320 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
25330 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
25340 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
25350 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
25360 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
25370 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
25380 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
25390 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
253a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
253b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
253c0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
253d0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
253e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
253f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25400 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
25410 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
25420 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
25430 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
25440 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
25450 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
25460 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
25470 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
25480 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
25490 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
254a0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
254b0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
254c0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
254d0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
254e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
254f0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
25500 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
25510 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
25520 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
25530 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
25540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
25550 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
25560 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
25570 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
25580 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
25590 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
255a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
255b0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
255c0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
255d0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
255e0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
255f0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
25600 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
25610 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
25620 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
25630 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
25640 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
25650 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
25660 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
25670 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25680 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
25690 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
256a0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
256b0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
256c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
256d0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
256e0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
256f0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
25700 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
25710 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25720 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
25730 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
25740 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
25750 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25760 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
25770 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
25780 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
25790 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
257a0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
257b0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
257c0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
257d0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
257e0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
257f0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
25800 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
25810 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
25820 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
25830 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
25840 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
25850 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
25860 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
25870 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
25880 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
25890 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
258a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
258b0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
258c0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
258d0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
258e0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
258f0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
25900 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
25910 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
25920 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
25930 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
25940 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
25950 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
25960 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
25970 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
25980 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
25990 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
259a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
259b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
259c0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
259d0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
259e0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
259f0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
25a00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
25a10 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
25a20 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
25a30 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
25a40 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
25a50 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
25a60 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
25a70 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
25a80 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
25a90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
25aa0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
25ab0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
25ac0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
25ad0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
25ae0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
25af0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
25b00 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
25b10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
25b20 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
25b30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
25b40 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
25b50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25b60 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
25b70 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
25b80 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
25b90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
25ba0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
25bb0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
25bc0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
25bd0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
25be0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
25bf0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
25c00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
25c10 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
25c20 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
25c30 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
25c40 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
25c50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
25c60 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
25c70 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
25c80 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
25c90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25ca0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
25cb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
25cc0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
25cd0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
25ce0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
25cf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
25d00 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
25d10 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
25d20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
25d30 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
25d40 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
25d50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
25d60 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
25d70 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
25d80 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
25d90 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
25da0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
25db0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
25dc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
25dd0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
25de0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25df0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
25e00 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
25e10 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
25e20 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
25e30 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
25e40 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
25e50 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
25e60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
25e70 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
25e80 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
25e90 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
25ea0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
25eb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
25ec0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
25ed0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25ee0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
25ef0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
25f00 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
25f10 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
25f20 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
25f30 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
25f40 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
25f50 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
25f60 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
25f70 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
25f80 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
25f90 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
25fa0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
25fb0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
25fc0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
25fd0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
25fe0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
25ff0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
26000 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
26010 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
26020 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
26030 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
26040 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
26050 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
26060 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
26070 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
26080 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
26090 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
260a0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
260b0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
260c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
260d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
260e0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
260f0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
26100 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
26110 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
26120 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
26130 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
26140 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
26150 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
26160 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
26170 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
26180 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
26190 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
261a0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
261b0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
261c0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
261d0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
261e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
261f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
26200 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
26210 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
26220 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
26230 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
26240 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
26250 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
26260 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
26270 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
26280 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
26290 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
262a0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
262b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
262c0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
262d0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
262e0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
262f0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
26300 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
26310 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
26320 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
26330 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
26340 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
26350 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
26360 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
26370 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
26380 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
26390 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
263a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
263b0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
263c0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
263d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
263e0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
263f0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
26400 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
26410 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
26420 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
26430 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
26440 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
26450 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
26460 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
26470 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
26480 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
26490 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
264a0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
264b0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
264c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
264d0 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
264e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
264f0 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
26500 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
26510 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
26520 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
26530 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
26540 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
26550 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
26560 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
26570 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26580 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
26590 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
265a0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
265b0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
265c0 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
265d0 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
265e0 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
265f0 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
26600 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
26610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
26620 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
26630 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
26640 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
26650 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
26660 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
26670 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
26680 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
26690 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
266a0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
266b0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
266c0 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
266d0 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
266e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
266f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26700 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
26710 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
26720 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
26730 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
26740 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
26750 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
26760 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
26770 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
26780 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
26790 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
267a0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
267b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
267c0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
267d0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
267e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
267f0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
26800 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
26810 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
26820 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
26830 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
26840 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
26850 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
26860 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
26870 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
26880 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
26890 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
268a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
268b0 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
268c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
268d0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
268e0 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
268f0 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
26900 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
26910 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
26920 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
26930 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
26940 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
26950 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
26960 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
26970 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
26980 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
26990 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
269a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
269b0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
269c0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
269d0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
269e0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
269f0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
26a00 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
26a10 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
26a20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
26a30 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
26a40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
26a50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26a60 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
26a70 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
26a80 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
26a90 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
26aa0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
26ab0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
26ac0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
26ad0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
26ae0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
26af0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
26b00 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
26b10 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
26b20 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
26b30 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
26b40 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
26b50 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
26b60 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
26b70 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
26b80 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
26b90 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
26ba0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
26bb0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
26bc0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
26bd0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
26be0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
26bf0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
26c00 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
26c10 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
26c20 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
26c30 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
26c40 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
26c50 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
26c60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26c70 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
26c80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
26c90 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
26ca0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
26cb0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
26cc0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
26cd0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26ce0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
26cf0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
26d00 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
26d10 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
26d20 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
26d30 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
26d40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26d50 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
26d60 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
26d70 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
26d80 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
26d90 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
26da0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
26db0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
26dc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
26dd0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
26de0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
26df0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
26e00 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
26e10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26e20 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
26e30 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
26e40 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
26e50 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
26e60 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
26e70 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
26e80 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
26e90 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
26ea0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
26eb0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
26ec0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
26ed0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
26ee0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
26ef0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
26f00 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26f10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26f20 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
26f30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26f40 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
26f50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
26f60 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
26f70 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
26f80 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
26f90 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
26fa0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
26fb0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
26fc0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
26fd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
26fe0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
26ff0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
27000 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
27010 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27020 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
27030 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
27040 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
27050 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27060 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
27070 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27080 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
27090 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
270a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
270b0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
270c0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
270d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
270e0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
270f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
27100 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
27110 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
27120 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27130 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27140 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
27150 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
27160 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
27170 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
27180 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27190 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
271a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
271b0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
271c0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
271d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
271e0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
271f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27200 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
27210 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
27220 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
27230 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
27240 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
27250 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
27260 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
27270 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
27280 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27290 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
272a0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
272b0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
272c0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
272d0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
272e0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
272f0 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
27300 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
27310 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
27320 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
27330 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
27340 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
27350 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
27360 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
27370 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
27380 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
27390 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
273a0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
273b0 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
273c0 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
273d0 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
273e0 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
273f0 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
27400 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
27410 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
27420 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
27430 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
27440 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
27450 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
27460 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27470 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
27480 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
27490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
274a0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
274b0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
274c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
274d0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
274e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
274f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27500 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
27510 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
27520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
27530 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
27540 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
27550 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
27560 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
27570 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27580 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
27590 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
275a0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
275b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
275c0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
275d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
275e0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
275f0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
27600 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
27610 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
27620 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
27630 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
27640 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
27650 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
27660 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
27670 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
27680 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
27690 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
276a0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
276b0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
276c0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
276d0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
276e0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
276f0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
27700 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
27710 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
27720 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
27730 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
27740 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
27750 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
27760 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
27770 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
27780 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
27790 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
277a0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
277b0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
277c0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
277d0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
277e0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
277f0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
27800 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
27810 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
27820 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
27830 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
27840 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
27850 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
27860 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
27870 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
27880 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
27890 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
278a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
278b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
278c0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
278d0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
278e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
278f0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
27900 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27910 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
27920 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
27930 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27940 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27950 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
27960 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
27970 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
27980 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
27990 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
279a0 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
279b0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
279c0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
279d0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
279e0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
279f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
27a00 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
27a10 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
27a20 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
27a30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27a40 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
27a50 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
27a60 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
27a70 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
27a80 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
27a90 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
27aa0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
27ab0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
27ac0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
27ad0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
27ae0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
27af0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
27b00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
27b10 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
27b20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
27b30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27b40 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
27b50 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
27b60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
27b70 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
27b80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27b90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
27ba0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
27bb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
27bc0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
27bd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
27be0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
27bf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27c00 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
27c10 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
27c20 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
27c30 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
27c40 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
27c50 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
27c60 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
27c70 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
27c80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27c90 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
27ca0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
27cb0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
27cc0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
27cd0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
27ce0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
27cf0 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ULL..*/.SQLITE_A
27d00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
27d10 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
27d20 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
27d30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
27d40 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
27d50 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
27d60 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
27d70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
27d80 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
27d90 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
27da0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
27db0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
27dc0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
27dd0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
27de0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
27df0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
27e00 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
27e10 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
27e20 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
27e30 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
27e40 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
27e50 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
27e60 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
27e70 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
27e80 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
27e90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27ea0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
27eb0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
27ec0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
27ed0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
27ee0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
27ef0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
27f00 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
27f10 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
27f20 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
27f30 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
27f40 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
27f50 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
27f60 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
27f70 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
27f80 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
27f90 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
27fa0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
27fb0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
27fc0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
27fd0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
27fe0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
27ff0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
28000 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28010 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
28020 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
28030 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
28040 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
28050 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28060 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
28070 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
28080 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
28090 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
280a0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
280b0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
280c0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
280d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
280e0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
280f0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
28100 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
28110 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
28120 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
28130 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
28140 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
28150 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
28160 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
28170 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
28180 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
28190 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
281a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
281b0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
281c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
281d0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
281e0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
281f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
28200 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
28210 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
28220 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
28230 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
28240 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
28250 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
28260 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
28270 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
28280 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
28290 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
282a0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
282b0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
282c0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
282d0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
282e0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
282f0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
28300 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
28310 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
28320 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28330 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
28340 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
28350 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
28360 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
28370 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
28380 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
28390 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
283a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
283b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
283c0 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
283d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
283e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
283f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28400 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
28410 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
28420 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
28430 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
28440 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
28450 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
28460 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
28470 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
28480 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
28490 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
284a0 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
284b0 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
284c0 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
284d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
284e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
284f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
28500 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
28510 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
28520 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
28530 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
28540 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
28550 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
28560 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
28570 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
28580 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
28590 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
285a0 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
285b0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
285c0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
285d0 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
285e0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
285f0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
28600 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
28610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28620 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
28630 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28640 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
28650 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
28660 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
28670 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
28680 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
28690 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
286a0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
286b0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
286c0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
286d0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
286e0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
286f0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
28700 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
28710 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
28720 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
28730 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
28740 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
28750 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
28760 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
28770 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
28780 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
28790 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
287a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
287b0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
287c0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
287d0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
287e0 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
287f0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
28800 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
28810 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
28820 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
28830 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
28840 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
28850 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
28860 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
28870 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
28880 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
28890 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
288a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
288b0 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
288c0 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
288d0 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
288e0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
288f0 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
28900 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
28910 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
28920 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
28930 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
28940 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
28950 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
28960 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
28970 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
28980 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
28990 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
289a0 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
289b0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
289c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
289d0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
289e0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
289f0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
28a00 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
28a10 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
28a20 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
28a30 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
28a40 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
28a50 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
28a60 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
28a70 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
28a80 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
28a90 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
28aa0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
28ab0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
28ac0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
28ad0 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
28ae0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
28af0 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
28b00 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
28b10 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
28b20 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
28b30 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
28b40 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
28b50 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
28b60 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
28b70 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
28b80 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
28b90 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
28ba0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
28bb0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
28bc0 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
28bd0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
28be0 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
28bf0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
28c00 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
28c10 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
28c20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
28c30 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
28c40 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
28c50 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
28c60 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
28c70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
28c80 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28c90 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
28ca0 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
28cb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
28cc0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
28cd0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28ce0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
28cf0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
28d00 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
28d10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
28d20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
28d30 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
28d40 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
28d50 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
28d60 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28d70 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
28d80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28d90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
28da0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28db0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
28dc0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
28dd0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
28de0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
28df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
28e00 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
28e10 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28e20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28e30 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
28e40 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
28e50 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
28e60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
28e70 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
28e80 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
28e90 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
28ea0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
28eb0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
28ec0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
28ed0 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
28ee0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
28ef0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
28f00 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
28f10 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
28f20 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
28f30 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
28f40 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
28f50 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
28f60 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
28f70 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
28f80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28f90 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
28fa0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
28fb0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
28fc0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
28fd0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
28fe0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
28ff0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
29000 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
29010 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
29020 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
29030 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
29040 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
29050 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
29060 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
29070 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
29080 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
29090 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
290a0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
290b0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
290c0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
290d0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
290e0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
290f0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
29100 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
29110 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
29120 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
29130 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
29140 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
29150 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
29160 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
29170 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
29180 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
29190 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
291a0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
291b0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
291c0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
291d0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
291e0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
291f0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
29200 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
29210 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
29220 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
29230 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
29240 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
29250 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
29260 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
29270 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
29280 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
29290 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
292a0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
292b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
292c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
292d0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
292e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
292f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
29300 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
29310 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
29320 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
29330 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
29340 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
29350 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
29360 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
29370 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29380 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
29390 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
293a0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
293b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
293c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
293d0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
293e0 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
293f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
29400 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29410 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
29420 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
29430 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
29440 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
29450 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
29460 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
29470 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
29480 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
29490 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
294a0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
294b0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
294c0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
294d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
294e0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
294f0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
29500 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
29510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29520 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29530 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
29540 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
29550 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
29560 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
29570 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
29580 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
29590 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
295a0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
295b0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
295c0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
295d0 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
295e0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
295f0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
29600 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
29610 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
29620 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
29630 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
29640 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
29650 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
29660 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
29670 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
29680 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
29690 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
296a0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
296b0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
296c0 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
296d0 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
296e0 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
296f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
29700 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
29710 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
29720 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
29730 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
29740 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
29750 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
29760 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
29770 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
29780 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
29790 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
297a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
297b0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
297c0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
297d0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
297e0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
297f0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
29800 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
29810 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
29820 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
29830 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
29840 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
29850 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
29860 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
29870 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
29880 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
29890 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
298a0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
298b0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
298c0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
298d0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
298e0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
298f0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
29900 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
29910 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
29920 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
29930 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
29940 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
29950 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29960 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
29970 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
29980 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
29990 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
299a0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
299b0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
299c0 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
299d0 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
299e0 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
299f0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
29a00 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
29a10 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
29a20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
29a30 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
29a40 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
29a50 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
29a60 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
29a70 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
29a80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
29a90 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
29aa0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
29ab0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
29ac0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
29ad0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
29ae0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
29af0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
29b00 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
29b10 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
29b20 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
29b30 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
29b40 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
29b50 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
29b60 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
29b70 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
29b80 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
29b90 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
29ba0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
29bb0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
29bc0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
29bd0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
29be0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
29bf0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
29c00 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
29c10 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
29c20 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
29c30 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
29c40 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
29c50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
29c60 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
29c70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
29c80 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
29c90 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
29ca0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
29cb0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
29cc0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
29cd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
29ce0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
29cf0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
29d00 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
29d10 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
29d20 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
29d30 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
29d40 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
29d50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29d60 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
29d70 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
29d80 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
29d90 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
29da0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
29db0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
29dc0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
29dd0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
29de0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
29df0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
29e00 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
29e10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29e20 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
29e30 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
29e40 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
29e50 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
29e60 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
29e70 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
29e80 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
29e90 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
29ea0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
29eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
29ec0 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
29ed0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
29ee0 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
29ef0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
29f00 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
29f10 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
29f20 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
29f30 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
29f40 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
29f50 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
29f60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29f70 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
29f80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
29f90 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
29fa0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
29fb0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
29fc0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
29fd0 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
29fe0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
29ff0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
2a000 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
2a010 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a020 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2a030 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
2a040 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
2a050 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
2a060 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
2a070 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
2a080 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
2a090 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
2a0a0 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
2a0b0 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
2a0c0 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
2a0d0 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
2a0e0 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
2a0f0 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
2a100 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
2a110 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
2a120 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
2a130 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2a140 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
2a150 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
2a160 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
2a170 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
2a180 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2a190 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
2a1a0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
2a1b0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
2a1c0 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
2a1d0 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
2a1e0 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
2a1f0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
2a200 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2a210 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
2a220 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
2a230 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
2a240 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a250 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2a260 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
2a270 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
2a280 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
2a290 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
2a2a0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
2a2b0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
2a2c0 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
2a2d0 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
2a2e0 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
2a2f0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
2a300 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
2a310 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
2a320 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
2a330 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
2a340 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
2a350 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
2a360 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a370 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2a380 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
2a390 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
2a3a0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
2a3b0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2a3c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a3d0 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
2a3e0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
2a3f0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
2a400 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
2a410 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
2a420 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
2a430 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
2a440 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
2a450 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2a460 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
2a470 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2a480 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
2a490 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a4a0 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
2a4b0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
2a4c0 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
2a4d0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2a4e0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
2a4f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2a500 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2a510 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
2a520 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2a530 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
2a540 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a550 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
2a560 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
2a570 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
2a580 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
2a590 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
2a5a0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
2a5b0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
2a5c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
2a5d0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
2a5e0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
2a5f0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2a600 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
2a610 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2a620 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2a630 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
2a640 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
2a650 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
2a660 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2a670 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
2a680 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
2a690 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2a6a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2a6b0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
2a6c0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
2a6d0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2a6e0 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
2a6f0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
2a700 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
2a710 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2a720 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2a730 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
2a740 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
2a750 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
2a760 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
2a770 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
2a780 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
2a790 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
2a7a0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
2a7b0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
2a7c0 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
2a7d0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
2a7e0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a7f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a800 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
2a810 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a820 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
2a830 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2a840 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a850 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2a860 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2a870 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2a880 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2a890 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2a8a0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2a8b0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2a8c0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2a8d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2a8e0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2a8f0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2a900 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2a910 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2a920 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2a930 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2a940 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2a950 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2a960 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2a970 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2a980 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2a990 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2a9a0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2a9b0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2a9c0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2a9d0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2a9e0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2a9f0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2aa00 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2aa10 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2aa20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2aa30 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2aa40 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2aa50 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2aa60 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2aa70 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2aa80 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2aa90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2aaa0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2aab0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2aac0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2aad0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2aae0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2aaf0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2ab00 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2ab10 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2ab20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2ab30 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2ab40 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2ab50 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2ab60 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2ab70 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2ab80 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2ab90 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2aba0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2abb0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
2abc0 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
2abd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2abe0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2abf0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2ac00 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2ac10 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2ac20 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2ac30 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
2ac40 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2ac50 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2ac60 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2ac70 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ac80 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2ac90 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2aca0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2acb0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2acc0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2acd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ace0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2acf0 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2ad00 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2ad10 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2ad20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2ad30 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2ad40 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2ad50 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2ad60 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2ad70 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2ad80 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2ad90 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
2ada0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2adb0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2adc0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
2add0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2ade0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2adf0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
2ae00 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2ae10 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2ae20 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2ae30 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2ae40 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2ae50 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2ae60 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2ae70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2ae80 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2ae90 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2aea0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2aeb0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2aec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2aed0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2aee0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2aef0 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2af00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2af10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2af20 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2af30 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2af40 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2af50 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2af60 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2af70 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2af80 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2af90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2afa0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2afb0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2afc0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2afd0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2afe0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2aff0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2b000 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2b010 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b020 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2b030 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2b040 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2b050 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2b060 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2b070 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2b080 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2b090 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2b0a0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2b0b0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2b0c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b0d0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2b0e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2b0f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
2b100 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
2b110 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
2b120 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
2b130 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
2b140 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
2b150 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2b160 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2b170 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2b180 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2b190 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2b1a0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2b1b0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2b1c0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2b1d0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2b1e0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2b1f0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2b200 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2b210 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2b220 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2b230 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2b240 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2b250 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2b260 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2b270 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b280 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2b290 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2b2a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2b2b0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2b2c0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2b2d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2b2e0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2b2f0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2b300 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
2b310 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2b320 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2b330 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2b340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b350 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2b360 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2b370 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2b380 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2b390 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2b3a0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
2b3b0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2b3c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b3d0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
2b3e0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2b3f0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
2b400 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2b410 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2b420 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2b430 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2b440 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2b450 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2b460 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2b470 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2b480 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2b490 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2b4a0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2b4b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2b4c0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2b4d0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2b4e0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2b4f0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2b500 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
2b510 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
2b520 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2b530 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
2b540 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2b550 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b560 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
2b570 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2b580 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2b590 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2b5a0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2b5b0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2b5c0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
2b5d0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2b5e0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
2b5f0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2b600 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
2b610 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2b620 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2b630 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2b640 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2b650 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2b660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b670 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
2b680 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2b690 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2b6a0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2b6b0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
2b6c0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2b6d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2b6e0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2b6f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2b700 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2b710 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b720 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
2b730 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
2b740 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2b750 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2b760 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2b770 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
2b780 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2b790 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
2b7a0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2b7b0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
2b7c0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
2b7d0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
2b7e0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
2b7f0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2b800 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2b810 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2b820 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2b830 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
2b840 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
2b850 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
2b860 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2b870 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
2b880 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
2b890 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2b8a0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
2b8b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b8c0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
2b8d0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
2b8e0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
2b8f0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
2b900 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
2b910 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
2b920 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
2b930 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2b940 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
2b950 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2b960 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2b970 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2b980 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2b990 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2b9a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b9b0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
2b9c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b9d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
2b9e0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
2b9f0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
2ba00 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
2ba10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
2ba20 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
2ba30 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
2ba40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2ba50 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
2ba60 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2ba70 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2ba80 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
2ba90 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
2baa0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
2bab0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
2bac0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2bad0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
2bae0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2baf0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2bb00 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
2bb10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2bb20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2bb30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2bb40 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
2bb50 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2bb60 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
2bb70 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
2bb80 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
2bb90 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
2bba0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
2bbb0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
2bbc0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
2bbd0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2bbe0 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
2bbf0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
2bc00 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
2bc10 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
2bc20 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
2bc30 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
2bc40 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
2bc50 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
2bc60 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
2bc70 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
2bc80 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
2bc90 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
2bca0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
2bcb0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
2bcc0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
2bcd0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
2bce0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2bcf0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2bd00 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
2bd10 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2bd20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2bd30 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2bd40 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
2bd50 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2bd60 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
2bd70 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
2bd80 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2bd90 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2bda0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
2bdb0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
2bdc0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2bdd0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2bde0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2bdf0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2be00 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2be10 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2be20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2be30 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2be40 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2be50 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2be60 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2be70 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2be80 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
2be90 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2bea0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
2beb0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
2bec0 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
2bed0 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
2bee0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2bef0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2bf00 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2bf10 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2bf20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2bf30 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2bf40 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2bf50 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
2bf60 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2bf70 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2bf80 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
2bf90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2bfa0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
2bfb0 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
2bfc0 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
2bfd0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2bfe0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
2bff0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
2c000 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2c010 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2c020 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2c030 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
2c040 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2c050 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
2c060 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2c070 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
2c080 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
2c090 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2c0a0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2c0b0 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
2c0c0 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
2c0d0 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
2c0e0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
2c0f0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
2c100 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
2c110 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
2c120 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
2c130 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
2c140 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
2c150 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
2c160 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
2c170 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
2c180 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
2c190 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
2c1a0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
2c1b0 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
2c1c0 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
2c1d0 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
2c1e0 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
2c1f0 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
2c200 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
2c210 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
2c220 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
2c230 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
2c240 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
2c250 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
2c260 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
2c270 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2c280 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2c290 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c2a0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
2c2b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2c2c0 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
2c2d0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2c2e0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
2c2f0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
2c300 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
2c310 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
2c320 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
2c330 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2c340 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2c350 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
2c360 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
2c370 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2c380 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2c390 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2c3a0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
2c3b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
2c3c0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
2c3d0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
2c3e0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
2c3f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2c400 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2c410 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
2c420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c430 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
2c440 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2c450 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2c460 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2c470 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2c480 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2c490 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
2c4a0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2c4b0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2c4c0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
2c4d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c4e0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
2c4f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c500 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
2c510 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2c520 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2c530 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
2c540 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2c550 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
2c560 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
2c570 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
2c580 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
2c590 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
2c5a0 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
2c5b0 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
2c5c0 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
2c5d0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
2c5e0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
2c5f0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
2c600 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
2c610 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
2c620 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
2c630 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
2c640 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
2c650 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
2c660 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
2c670 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
2c680 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
2c690 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
2c6a0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
2c6b0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
2c6c0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
2c6d0 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
2c6e0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
2c6f0 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
2c700 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
2c710 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
2c720 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
2c730 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
2c740 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
2c750 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2c760 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2c770 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c780 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2c790 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2c7a0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
2c7b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c7c0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2c7d0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2c7e0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2c7f0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2c800 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c810 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
2c820 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
2c830 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
2c840 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
2c850 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
2c860 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2c870 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
2c880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c890 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
2c8a0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
2c8b0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
2c8c0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
2c8d0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
2c8e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2c8f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2c900 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
2c910 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
2c920 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
2c930 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
2c940 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2c950 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
2c960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2c970 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
2c980 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2c990 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
2c9a0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
2c9b0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2c9c0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
2c9d0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
2c9e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c9f0 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
2ca00 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2ca10 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2ca20 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2ca30 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2ca40 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2ca50 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2ca60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2ca70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ca80 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2ca90 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2caa0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
2cab0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
2cac0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
2cad0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
2cae0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
2caf0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
2cb00 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
2cb10 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
2cb20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2cb30 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2cb40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2cb50 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2cb60 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2cb70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
2cb80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2cb90 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2cba0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2cbb0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2cbc0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2cbd0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2cbe0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2cbf0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2cc00 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2cc10 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2cc20 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2cc30 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2cc40 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2cc50 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2cc60 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2cc70 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2cc80 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2cc90 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
2cca0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2ccb0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ccc0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
2ccd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2cce0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2ccf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2cd00 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2cd10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cd20 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2cd30 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2cd40 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
2cd50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cd60 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
2cd70 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2cd80 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2cd90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2cda0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2cdb0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2cdc0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2cdd0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2cde0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2cdf0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2ce00 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2ce10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ce20 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2ce30 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
2ce40 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2ce50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
2ce60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ce70 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2ce80 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2ce90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2cea0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2ceb0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2cec0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2ced0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2cee0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2cef0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2cf00 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
2cf10 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
2cf20 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
2cf30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2cf40 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
2cf50 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
2cf60 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2cf70 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2cf80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2cf90 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2cfa0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2cfb0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2cfc0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2cfd0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2cfe0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2cff0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2d000 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
2d010 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
2d020 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2d030 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
2d040 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
2d050 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
2d060 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
2d070 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
2d080 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2d090 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
2d0a0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
2d0b0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
2d0c0 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
2d0d0 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
2d0e0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
2d0f0 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
2d100 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2d110 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2d120 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
2d130 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
2d140 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
2d150 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
2d160 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
2d170 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
2d180 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
2d190 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
2d1a0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
2d1b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
2d1c0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2d1d0 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
2d1e0 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
2d1f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d200 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
2d210 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
2d220 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2d230 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
2d240 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
2d250 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
2d260 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
2d270 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2d280 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
2d290 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
2d2a0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
2d2b0 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
2d2c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d2d0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
2d2e0 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
2d2f0 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
2d300 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
2d310 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2d320 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
2d330 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
2d340 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2d350 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2d360 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
2d370 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
2d380 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2d390 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2d3a0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
2d3b0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
2d3c0 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
2d3d0 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
2d3e0 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
2d3f0 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
2d400 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2d410 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2d420 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2d430 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d440 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2d450 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2d460 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2d470 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2d480 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2d490 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2d4a0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2d4b0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2d4c0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2d4d0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2d4e0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2d4f0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2d500 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2d510 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2d520 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2d530 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2d540 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2d550 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2d560 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2d570 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2d580 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2d590 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2d5a0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2d5b0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2d5c0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2d5d0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2d5e0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2d5f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d600 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2d610 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2d620 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2d630 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2d640 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2d650 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2d660 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2d670 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d680 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2d690 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2d6a0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2d6b0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2d6c0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2d6d0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2d6e0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2d6f0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2d700 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2d710 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2d720 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2d730 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2d740 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2d750 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2d760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2d770 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2d780 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2d790 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2d7a0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2d7b0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2d7c0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2d7d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2d7e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2d7f0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2d800 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2d810 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2d820 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2d830 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2d840 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2d850 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d860 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
2d870 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2d880 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d890 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
2d8a0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
2d8b0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
2d8c0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
2d8d0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
2d8e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2d8f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d900 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
2d910 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2d920 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d930 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
2d940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
2d950 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
2d960 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
2d970 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2d980 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
2d990 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2d9a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2d9b0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
2d9c0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
2d9d0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
2d9e0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
2d9f0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2da00 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
2da10 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
2da20 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
2da30 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
2da40 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
2da50 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
2da60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
2da70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2da80 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
2da90 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
2daa0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
2dab0 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
2dac0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2dad0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
2dae0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2daf0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2db00 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2db10 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
2db20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2db30 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
2db40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
2db50 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
2db60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
2db70 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
2db80 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2db90 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
2dba0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2dbb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
2dbc0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
2dbd0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
2dbe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
2dbf0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
2dc00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2dc10 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2dc20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2dc30 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
2dc40 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
2dc50 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
2dc60 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
2dc70 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
2dc80 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
2dc90 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
2dca0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
2dcb0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
2dcc0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
2dcd0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
2dce0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
2dcf0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
2dd00 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
2dd10 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
2dd20 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
2dd30 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2dd40 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2dd50 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2dd60 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2dd70 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
2dd80 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2dd90 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
2dda0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
2ddb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2ddc0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2ddd0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2dde0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2ddf0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
2de00 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
2de10 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2de20 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2de30 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2de40 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2de50 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
2de60 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
2de70 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
2de80 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
2de90 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2dea0 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
2deb0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
2dec0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
2ded0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2dee0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
2def0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
2df00 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2df10 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
2df20 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
2df30 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
2df40 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
2df50 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
2df60 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
2df70 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
2df80 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
2df90 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63    Every SQL func
2dfa0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2dfb0 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65  ion must be able
2dfc0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
2dfd0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
2dfe0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
2dff0 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
2e000 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
2e010 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
2e020 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
2e030 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
2e040 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
2e050 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
2e060 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e070 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2e080 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e090 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2e0a0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2e0b0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2e0c0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2e0d0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2e0e0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
2e0f0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
2e100 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2e110 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2e120 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
2e130 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
2e140 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
2e150 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
2e160 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
2e170 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
2e180 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
2e190 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
2e1a0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
2e1b0 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
2e1c0 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
2e1d0 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
2e1e0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
2e1f0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
2e200 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
2e210 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
2e220 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2e230 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2e240 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2e250 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2e260 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2e270 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2e280 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2e290 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2e2a0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
2e2b0 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
2e2c0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
2e2d0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
2e2e0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
2e2f0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
2e300 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
2e310 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
2e320 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2e330 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2e340 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
2e350 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2e360 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2e370 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2e380 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
2e390 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
2e3a0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
2e3b0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2e3c0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2e3d0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2e3e0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
2e3f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2e400 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2e410 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
2e420 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
2e430 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
2e440 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
2e450 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
2e460 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
2e470 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2e480 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
2e490 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
2e4a0 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
2e4b0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
2e4c0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
2e4d0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
2e4e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2e4f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e500 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
2e510 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
2e520 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
2e530 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2e540 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
2e550 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
2e560 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
2e570 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2e580 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
2e590 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
2e5a0 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
2e5b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e5c0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
2e5d0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
2e5e0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
2e5f0 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
2e600 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2e610 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2e620 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
2e630 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
2e640 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
2e650 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
2e660 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
2e670 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
2e680 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
2e690 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
2e6a0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2e6b0 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
2e6c0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
2e6d0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2e6e0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
2e6f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2e700 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
2e710 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
2e720 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
2e730 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2e740 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
2e750 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
2e760 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
2e770 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
2e780 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
2e790 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
2e7a0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
2e7b0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2e7c0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
2e7d0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
2e7e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
2e7f0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
2e800 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
2e810 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
2e820 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
2e830 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
2e840 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e850 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
2e860 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
2e870 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
2e880 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2e890 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e8a0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
2e8b0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
2e8c0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
2e8d0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
2e8e0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
2e8f0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
2e900 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2e910 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
2e920 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2e930 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2e940 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2e950 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
2e960 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2e970 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2e980 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
2e990 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
2e9a0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
2e9b0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
2e9c0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2e9d0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2e9e0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
2e9f0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
2ea00 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
2ea10 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
2ea20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
2ea30 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
2ea40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2ea50 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
2ea60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2ea70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
2ea80 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
2ea90 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
2eaa0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
2eab0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
2eac0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
2ead0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
2eae0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
2eaf0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
2eb00 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2eb10 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2eb20 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
2eb30 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2eb40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2eb50 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2eb60 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
2eb70 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2eb80 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
2eb90 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2eba0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2ebb0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2ebc0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2ebd0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2ebe0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2ebf0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2ec00 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2ec10 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2ec20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2ec30 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2ec40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ec50 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
2ec60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2ec70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2ec80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2ec90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2eca0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2ecb0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2ecc0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2ecd0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2ece0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2ecf0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2ed00 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2ed10 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2ed20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2ed30 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2ed40 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2ed50 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2ed60 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
2ed70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2ed80 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ed90 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2eda0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2edb0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2edc0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2edd0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2ede0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2edf0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2ee00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2ee10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2ee20 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2ee30 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2ee40 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2ee50 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2ee60 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2ee70 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
2ee80 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2ee90 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2eea0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
2eeb0 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
2eec0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
2eed0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
2eee0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
2eef0 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
2ef00 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
2ef10 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
2ef20 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
2ef30 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
2ef40 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2ef50 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
2ef60 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
2ef70 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
2ef80 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2ef90 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
2efa0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
2efb0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2efc0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
2efd0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
2efe0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
2eff0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f000 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
2f010 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2f020 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
2f030 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2f040 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
2f050 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
2f060 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
2f070 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
2f080 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
2f090 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2f0a0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
2f0b0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
2f0c0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
2f0d0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2f0e0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
2f0f0 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
2f100 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
2f110 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
2f120 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
2f130 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2f140 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
2f150 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
2f160 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
2f170 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
2f180 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
2f190 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
2f1a0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
2f1b0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
2f1c0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
2f1d0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
2f1e0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
2f1f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
2f200 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2f210 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
2f220 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
2f230 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
2f240 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2f250 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2f260 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
2f270 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
2f280 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
2f290 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2f2a0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
2f2b0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2f2c0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
2f2d0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
2f2e0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
2f2f0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2f300 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
2f310 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
2f320 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2f330 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
2f340 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
2f350 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
2f360 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2f370 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2f380 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2f390 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2f3a0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2f3b0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2f3c0 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
2f3d0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2f3e0 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
2f3f0 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
2f400 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
2f410 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
2f420 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
2f430 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2f440 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
2f450 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
2f460 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
2f470 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
2f480 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
2f490 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
2f4a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
2f4b0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
2f4c0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
2f4d0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
2f4e0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
2f4f0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
2f500 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f510 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2f520 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f530 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2f540 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
2f550 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
2f560 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2f570 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2f580 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
2f590 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
2f5a0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
2f5b0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2f5c0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
2f5d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f5e0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
2f5f0 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
2f600 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2f610 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
2f620 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
2f630 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
2f640 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2f650 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
2f660 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
2f670 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2f680 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
2f690 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2f6a0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
2f6b0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2f6c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2f6d0 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
2f6e0 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
2f6f0 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
2f700 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2f710 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
2f720 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
2f730 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
2f740 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
2f750 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2f760 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2f770 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
2f780 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2f790 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
2f7a0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
2f7b0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2f7c0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2f7d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f7e0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
2f7f0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2f800 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2f810 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2f820 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2f830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f840 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2f850 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
2f860 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
2f870 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
2f880 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
2f890 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
2f8a0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
2f8b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f8c0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2f8d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f8e0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2f8f0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
2f900 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
2f910 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
2f920 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
2f930 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
2f940 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
2f950 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2f960 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2f970 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
2f980 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
2f990 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
2f9a0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
2f9b0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
2f9c0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
2f9d0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
2f9e0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
2f9f0 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
2fa00 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
2fa10 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
2fa20 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
2fa30 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
2fa40 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
2fa50 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
2fa60 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
2fa70 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
2fa80 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
2fa90 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2faa0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
2fab0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
2fac0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
2fad0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
2fae0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
2faf0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
2fb00 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
2fb10 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2fb20 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2fb30 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2fb40 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2fb50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2fb60 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2fb70 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2fb80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2fb90 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2fba0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2fbb0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2fbc0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2fbd0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2fbe0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2fbf0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2fc00 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2fc10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2fc20 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2fc30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fc40 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2fc50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2fc60 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2fc70 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2fc80 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2fc90 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2fca0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2fcb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2fcc0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c  rameters..*/.SQL
2fcd0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2fce0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2fcf0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
2fd00 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2fd10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
2fd20 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
2fd30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2fd40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2fd50 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2fd60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2fd70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
2fd80 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2fd90 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2fda0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2fdb0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2fdc0 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
2fdd0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2fde0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
2fdf0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2fe00 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2fe10 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2fe20 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
2fe30 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2fe40 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
2fe50 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2fe60 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2fe70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2fe80 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
2fe90 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2fea0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2feb0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2fec0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2fed0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2fee0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2fef0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2ff00 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
2ff10 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2ff20 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2ff30 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
2ff40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2ff50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ff60 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2ff70 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2ff80 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
2ff90 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
2ffa0 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
2ffb0 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
2ffc0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
2ffd0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
2ffe0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
2fff0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
30000 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
30010 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
30020 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
30030 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
30040 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
30050 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
30060 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
30070 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
30080 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
30090 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
300a0 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
300b0 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
300c0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
300d0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
300e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
300f0 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
30100 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
30110 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
30120 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
30130 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
30140 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
30150 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
30160 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
30170 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
30180 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
30190 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
301a0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
301b0 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
301c0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
301d0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
301e0 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
301f0 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
30200 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
30210 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
30220 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
30230 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
30240 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
30250 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
30260 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
30270 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
30280 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
30290 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
302a0 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
302b0 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
302c0 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
302d0 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
302e0 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
302f0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
30300 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
30310 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
30320 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
30330 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
30340 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30350 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30360 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
30370 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
30380 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69  L pointer if N i
30390 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f  s.** less than o
303a0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
303b0 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  or if a memory a
303c0 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
303d0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
303e0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
303f0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
30400 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
30410 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
30420 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
30430 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
30440 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
30450 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
30460 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
30470 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
30480 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
30490 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
304a0 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
304b0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
304c0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
304d0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
304e0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
304f0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
30500 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  n.)^.**.** ^SQLi
30510 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
30520 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
30530 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
30540 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
30550 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
30560 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
30570 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
30580 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
30590 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
305a0 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
305b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
305c0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
305d0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
305e0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
305f0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
30600 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
30610 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
30620 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
30630 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
30640 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
30650 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
30660 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
30670 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
30680 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
30690 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
306a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
306b0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
306c0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
306d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
306e0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
306f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
30700 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
30710 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
30720 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
30730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30740 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
30750 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30760 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
30770 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
30780 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
30790 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
307a0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
307b0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
307c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
307d0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
307e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
307f0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
30800 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
30810 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
30820 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
30830 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
30840 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
30850 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
30860 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
30870 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
30880 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
30890 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
308a0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
308b0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
308c0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
308d0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
308e0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
308f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
30900 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
30910 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
30920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30930 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
30940 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
30950 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
30960 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
30970 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
30980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
30990 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
309a0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
309b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
309c0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
309d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
309e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
309f0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
30a00 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
30a10 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
30a20 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
30a30 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ction..*/.SQLITE
30a40 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
30a50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
30a60 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
30a70 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
30a80 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
30a90 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
30aa0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ata.**.** The fo
30ab0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
30ac0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
30ad0 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
30ae0 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
30af0 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
30b00 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
30b10 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
30b20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
30b30 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
30b40 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
30b50 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
30b60 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
30b70 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
30b80 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
30b90 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
30ba0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
30bb0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
30bc0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
30bd0 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
30be0 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
30bf0 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
30c00 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
30c10 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
30c20 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
30c30 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
30c40 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
30c50 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
30c60 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
30c70 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
30c80 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
30c90 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
30ca0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
30cb0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
30cc0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
30cd0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
30ce0 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
30cf0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
30d00 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
30d10 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
30d20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
30d30 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
30d40 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
30d50 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
30d60 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
30d70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30d80 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
30d90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30da0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30db0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
30dc0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
30dd0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
30de0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
30df0 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
30e00 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
30e10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30e20 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30e30 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61  n. ^If no metada
30e40 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
30e50 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
30e60 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
30e70 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
30e80 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
30e90 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
30ea0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
30eb0 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
30ec0 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
30ed0 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
30ee0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
30ef0 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
30f00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
30f10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30f20 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
30f30 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
30f40 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
30f50 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69   pointed to by i
30f60 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
30f70 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   as the metadata
30f80 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
30f90 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
30fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30fb0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
30fc0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
30fd0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
30fe0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
30ff0 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
31000 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
31010 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
31020 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  oyed..** ^If it 
31030 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
31040 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
31050 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
31060 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e  * function given
31070 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61   by the 4th para
31080 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
31090 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f  _set_auxdata() o
310a0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74  n.** the metadat
310b0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
310c0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
310d0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
310e0 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
310f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
31100 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
31110 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
31120 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
31130 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
31140 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
31150 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61  nd drop metadata
31160 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d   on any.** param
31170 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63  eter of any func
31180 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65  tion at any time
31190 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61  .  ^The only gua
311a0 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a  rantee is that.*
311b0 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  * the destructor
311c0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
311d0 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
311e0 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a  ata is dropped..
311f0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
31200 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
31210 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
31220 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
31230 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73  s for.** express
31240 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f  ions that are co
31250 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c  nstant at compil
31260 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63  e time. This inc
31270 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a  ludes literal.**
31280 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
31290 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a  ameters].)^.**.*
312a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
312b0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
312c0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
312d0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
312e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
312f0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
31300 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
31310 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
31320 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
31330 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
31340 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
31350 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
31360 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
31370 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
31380 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
31390 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
313a0 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
313b0 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
313c0 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
313d0 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
313e0 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
313f0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
31400 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
31410 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
31420 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
31430 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
31440 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
31450 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
31460 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
31470 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
31480 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
31490 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
314a0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
314b0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
314c0 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
314d0 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
314e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
314f0 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
31500 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
31510 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
31520 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
31530 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
31540 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
31550 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
31560 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
31570 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
31580 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
31590 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
315a0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
315b0 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
315c0 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
315d0 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
315e0 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
315f0 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
31600 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
31610 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
31620 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
31630 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
31640 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
31650 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
31660 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
31670 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
31680 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
31690 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
316a0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
316b0 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
316c0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
316d0 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
316e0 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
316f0 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
31700 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
31710 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
31720 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
31730 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
31740 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
31750 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
31760 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
31770 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31780 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
31790 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
317a0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
317b0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
317c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
317d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
317e0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
317f0 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
31800 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
31810 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
31820 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
31830 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
31840 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
31850 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
31860 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
31870 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
31880 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
31890 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
318a0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
318b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
318c0 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
318d0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
318e0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
318f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31900 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
31910 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
31920 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
31930 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
31940 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
31950 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
31960 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
31970 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
31980 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
31990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
319a0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
319b0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
319c0 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
319d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
319e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
319f0 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
31a00 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
31a10 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
31a20 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
31a30 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
31a40 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
31a50 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
31a60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31a70 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
31a80 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
31a90 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
31aa0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
31ab0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31ac0 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
31ad0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
31ae0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
31af0 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
31b00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31b10 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31b20 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
31b30 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31b40 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
31b50 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
31b60 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
31b70 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
31b80 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
31b90 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
31ba0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
31bb0 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
31bc0 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
31bd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
31be0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31bf0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
31c00 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
31c10 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
31c20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
31c30 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
31c40 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
31c50 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
31c60 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
31c70 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
31c80 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
31c90 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
31ca0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31cb0 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
31cc0 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
31cd0 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
31ce0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
31cf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
31d00 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
31d10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31d20 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
31d30 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
31d40 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
31d50 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
31d60 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
31d70 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
31d80 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
31d90 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
31da0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
31db0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31dc0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
31dd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
31de0 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
31df0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
31e00 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
31e10 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
31e20 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
31e30 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
31e40 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
31e50 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
31e60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31e70 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
31e80 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31e90 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
31ea0 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
31eb0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
31ec0 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
31ed0 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
31ee0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
31ef0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
31f00 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
31f10 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
31f20 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
31f30 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
31f40 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
31f50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31f60 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
31f70 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
31f80 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
31f90 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
31fa0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
31fb0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
31fc0 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
31fd0 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
31fe0 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
31ff0 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
32000 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
32010 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32020 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
32030 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32040 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
32050 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
32060 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
32070 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32080 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
32090 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
320a0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
320b0 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
320c0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
320d0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
320e0 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
320f0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
32100 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32110 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
32120 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
32130 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
32140 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
32150 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
32160 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
32170 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
32180 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32190 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
321a0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
321b0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
321c0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
321d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
321e0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
321f0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
32200 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
32210 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
32220 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
32230 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
32240 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
32250 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
32260 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
32270 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32280 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
32290 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
322a0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
322b0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
322c0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
322d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
322e0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
322f0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
32300 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
32310 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
32320 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32330 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
32340 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
32350 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32360 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
32370 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
32380 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
32390 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
323a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
323b0 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
323c0 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
323d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
323e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
323f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32400 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
32410 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
32420 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
32430 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
32440 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32450 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
32460 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
32470 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
32480 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
32490 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
324a0 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
324b0 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
324c0 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
324d0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
324e0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
324f0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
32500 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
32510 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
32520 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
32530 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
32540 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
32550 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
32560 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
32570 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
32580 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
32590 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
325a0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
325b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
325c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
325d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
325e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
325f0 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
32600 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
32610 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
32620 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
32630 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
32640 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
32650 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
32660 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
32670 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
32680 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
32690 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
326a0 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
326b0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
326c0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
326d0 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
326e0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
326f0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
32700 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
32710 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
32720 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
32730 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
32740 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
32750 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
32760 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
32770 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
32780 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
32790 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
327a0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
327b0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
327c0 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
327d0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
327e0 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
327f0 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
32800 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
32810 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
32820 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
32830 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
32840 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
32850 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
32860 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
32870 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
32880 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
32890 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
328a0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
328b0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
328c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
328d0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
328e0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
328f0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
32900 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
32910 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
32920 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
32930 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
32940 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
32950 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
32960 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
32970 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
32980 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
32990 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
329a0 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
329b0 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
329c0 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
329d0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
329e0 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
329f0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
32a00 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
32a10 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
32a20 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
32a30 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
32a40 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
32a50 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
32a60 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
32a70 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
32a80 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
32a90 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
32aa0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
32ab0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
32ac0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
32ad0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
32ae0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
32af0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
32b00 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
32b10 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
32b20 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
32b30 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
32b40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
32b50 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
32b60 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
32b70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32b80 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
32b90 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
32ba0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
32bb0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32bc0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32bd0 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
32be0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
32bf0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32c00 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
32c10 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
32c20 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
32c30 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
32c40 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
32c50 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
32c60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
32c70 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
32c80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
32c90 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
32ca0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
32cb0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
32cc0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
32cd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
32ce0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
32cf0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
32d00 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
32d10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32d20 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
32d30 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
32d40 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
32d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
32d60 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
32d70 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
32d80 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
32d90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
32da0 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
32db0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
32dc0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
32dd0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
32de0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
32df0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
32e00 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
32e10 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
32e20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32e30 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32e40 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
32e50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
32e60 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
32e70 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
32e80 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
32e90 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
32eb0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
32ec0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
32ed0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
32ee0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
32ef0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
32f00 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
32f10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
32f20 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41  ouble);.SQLITE_A
32f30 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32f40 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
32f50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
32f60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
32f70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
32f80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32f90 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
32fa0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32fb0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51   void*, int);.SQ
32fc0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32fd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32fe0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
32ff0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
33000 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
33010 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33020 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
33030 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
33040 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
33050 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
33060 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
33070 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  text*, int);.SQL
33080 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
33090 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
330a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
330b0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
330c0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
330d0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
330e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
330f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53  qlite3_int64);.S
33100 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
33120 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
33130 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
33140 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
33150 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
33160 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33170 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
33180 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
33190 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
331a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
331b0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
331c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
331d0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
331e0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
331f0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
33200 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
33210 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
33220 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
33230 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
33240 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
33250 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
33260 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
33270 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33280 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
33290 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
332a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
332b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
332c0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
332d0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
332e0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
332f0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
33300 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
33310 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
33320 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
33330 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
33340 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
33350 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
33360 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
33370 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
33380 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
33390 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
333a0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
333b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
333c0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
333d0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
333e0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
333f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
33400 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
33410 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
33420 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33430 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
33440 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33450 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
33460 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
33470 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
33480 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
33490 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
334a0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
334b0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
334c0 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
334d0 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
334e0 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
334f0 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
33500 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
33510 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
33520 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
33530 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
33540 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
33550 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
33560 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
33570 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
33580 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
33590 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
335a0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
335b0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
335c0 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
335d0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
335e0 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
335f0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
33600 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
33610 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
33620 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
33630 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
33640 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
33650 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
33660 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
33670 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
33680 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
33690 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
336a0 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
336b0 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
336c0 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
336d0 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
336e0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
336f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
33700 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
33710 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
33720 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
33730 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
33740 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
33750 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
33760 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
33770 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
33780 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
33790 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
337a0 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
337b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
337c0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
337d0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
337e0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
337f0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
33800 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
33810 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
33820 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33830 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
33840 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33850 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
33860 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
33870 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
33880 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
33890 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
338a0 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
338b0 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
338c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
338d0 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
338e0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
338f0 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
33900 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
33910 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
33920 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
33930 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33940 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
33950 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
33960 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
33970 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
33980 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
33990 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
339a0 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
339b0 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
339c0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
339d0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
339e0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
339f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
33a00 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
33a10 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
33a20 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
33a30 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
33a40 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
33a50 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
33a60 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
33a70 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33a80 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
33a90 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
33aa0 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
33ab0 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
33ac0 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
33ad0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
33ae0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
33af0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
33b00 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
33b10 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
33b20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33b30 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
33b40 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
33b50 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
33b60 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
33b70 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
33b80 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33b90 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
33ba0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
33bb0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
33bc0 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
33bd0 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
33be0 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
33bf0 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
33c00 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
33c10 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
33c20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
33c30 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
33c40 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
33c50 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
33c60 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
33c70 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
33c80 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
33c90 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
33ca0 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
33cb0 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
33cc0 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
33cd0 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
33ce0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
33cf0 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
33d00 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
33d10 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
33d20 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
33d30 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
33d40 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
33d50 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
33d60 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
33d70 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
33d80 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
33d90 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
33da0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
33db0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
33dc0 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
33dd0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
33de0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33df0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
33e00 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
33e10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33e20 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
33e30 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
33e40 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
33e50 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
33e60 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
33e70 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33e80 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
33e90 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
33ea0 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
33eb0 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
33ec0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
33ed0 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
33ee0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
33ef0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
33f00 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
33f10 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
33f20 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
33f30 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
33f40 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
33f50 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
33f60 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
33f70 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
33f80 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
33f90 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33fa0 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
33fb0 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
33fc0 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
33fd0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
33fe0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
33ff0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
34000 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
34010 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
34020 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
34030 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
34040 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34050 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
34060 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
34070 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
34080 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
34090 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
340a0 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
340b0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
340c0 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
340d0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
340e0 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
340f0 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
34100 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
34110 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
34120 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
34130 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
34140 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
34150 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
34160 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34170 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
34180 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34190 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ed16()]..*/.SQLI
341a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
341b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
341c0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
341d0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
341e0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
341f0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
34200 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
34210 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
34220 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
34230 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
34240 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34250 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34260 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
34270 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
34280 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
34290 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
342a0 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
342b0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
342c0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
342d0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
342e0 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
342f0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
34300 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
34310 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
34320 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
34330 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
34340 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
34350 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
34360 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
34370 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
34380 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
34390 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
343a0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
343b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
343c0 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
343d0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
343e0 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
343f0 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
34400 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
34410 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
34420 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
34430 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
34440 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
34450 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
34460 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
34470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34480 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
34490 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
344a0 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
344b0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
344c0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
344d0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
344e0 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
344f0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
34500 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34510 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
34520 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
34530 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
34540 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
34550 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
34560 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
34570 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
34580 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
34590 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
345a0 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
345b0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
345c0 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
345d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
345e0 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
345f0 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
34600 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
34610 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
34620 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
34630 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
34640 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
34650 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
34660 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
34670 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
34680 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
34690 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
346a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
346b0 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
346c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
346d0 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
346e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
346f0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
34700 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
34710 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
34720 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
34730 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
34740 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
34750 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
34760 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
34770 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
34780 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
34790 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
347a0 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
347b0 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
347c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
347d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
347e0 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
347f0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
34800 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
34810 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
34820 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
34830 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
34840 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
34850 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34860 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
34870 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34880 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
34890 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
348a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
348b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
348c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
348d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
348e0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
348f0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
34900 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
34910 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
34920 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54   char*).);.SQLIT
34930 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34940 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34950 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
34960 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
34970 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
34980 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
34990 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
349a0 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
349b0 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
349c0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
349d0 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
349e0 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
349f0 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
34a00 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
34a10 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
34a20 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
34a30 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
34a40 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
34a50 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
34a60 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
34a70 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
34a80 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
34a90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  I int sqlite3_ke
34aa0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
34ab0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
34ac0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
34ad0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
34ae0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
34af0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
34b00 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
34b10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
34b20 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
34b30 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
34b40 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
34b50 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
34b60 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
34b70 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
34b80 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
34b90 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
34ba0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
34bb0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
34bc0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
34bd0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
34be0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
34bf0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
34c00 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
34c10 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
34c20 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
34c30 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
34c40 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
34c50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
34c60 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
34c70 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
34c80 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
34c90 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
34ca0 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
34cb0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
34cc0 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
34cd0 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62   for a SEE datab
34ce0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
34cf0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
34d00 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74   of the SEE rout
34d10 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
34d20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
34d30 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
34d40 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74  ate_see(.  const
34d50 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
34d60 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
34d70 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
34d80 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66  /.);.#endif..#if
34d90 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  def SQLITE_ENABL
34da0 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70  E_CEROD./*.** Sp
34db0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
34dc0 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43  tion key for a C
34dd0 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20  EROD database.  
34de0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
34df0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
34e00 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73  e CEROD routines
34e10 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53   will work..*/.S
34e20 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
34e30 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
34e40 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63  cerod(.  const c
34e50 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
34e60 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
34e70 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
34e80 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
34e90 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
34ea0 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
34eb0 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a   A Short Time.**
34ec0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
34ed0 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
34ee0 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
34ef0 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
34f00 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
34f10 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
34f20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
34f30 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
34f40 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
34f50 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ter..**.** If th
34f60 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
34f70 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
34f80 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
34f90 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
34fa0 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
34fb0 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
34fc0 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
34fd0 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
34fe0 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
34ff0 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  d. The number of
35000 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
35010 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
35020 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
35030 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
35040 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
35050 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
35060 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
35070 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
35080 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
35090 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
350a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
350b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
350c0 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65  t.  If the xSlee
350d0 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  p() method.** of
350e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
350f0 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
35100 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f  ted correctly, o
35110 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  r not implemente
35120 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65  d at.** all, the
35130 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
35140 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  f sqlite3_sleep(
35150 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72  ) may deviate fr
35160 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69  om the descripti
35170 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65  on.** in the pre
35180 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73  vious paragraphs
35190 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
351a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
351b0 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
351c0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
351d0 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
351e0 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
351f0 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
35200 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
35210 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
35220 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
35230 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
35240 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
35250 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
35260 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
35270 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
35280 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
35290 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
352a0 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74   built-in [sqlit
352b0 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a  e3_vfs | VFS].**
352c0 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
352d0 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
352e0 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76  y.)^  ^If this v
352f0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
35300 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
35310 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
35320 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
35330 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
35340 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
35350 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
35360 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
35370 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
35380 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
35390 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   in more than on
353a0 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61  e.** thread at a
353b0 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f   time.  It is no
353c0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
353d0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
353e0 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b  riable.** if a [
353f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35400 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73  ion] is being us
35410 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ed at the same t
35420 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74  ime in a separat
35430 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20  e.** thread..** 
35440 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
35450 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
35460 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
35470 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
35480 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
35490 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
354a0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
354b0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
354c0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
354d0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61  and that this va
354e0 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e  riable remain un
354f0 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65  changed.** there
35500 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  after..**.** ^Th
35510 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
35520 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
35530 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20  may modify this 
35540 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75  variable and cau
35550 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e  se.** it to poin
35560 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
35570 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
35580 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75  e3_malloc].  ^Fu
35590 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68  rthermore,.** th
355a0 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
355b0 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
355c0 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74  always assumes t
355d0 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a  hat any string.*
355e0 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  * that this vari
355f0 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  able points to i
35600 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  s held in memory
35610 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
35620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
35630 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67  oc] and the prag
35640 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  ma may attempt t
35650 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f  o free that memo
35660 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ry.** using [sql
35670 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48  ite3_free]..** H
35680 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61  ence, if this va
35690 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69  riable is modifi
356a0 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74  ed directly, eit
356b0 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65  her it should be
356c0 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72  .** made NULL or
356d0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
356e0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
356f0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
35700 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c  malloc].** or el
35710 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  se the use of th
35720 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
35730 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
35740 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
35750 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
35760 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
35770 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
35780 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
35790 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
357a0 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
357b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
357c0 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74  _open] or [sqlit
357d0 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74  e3_open_v2].  Ot
357e0 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
357f0 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
35800 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
35810 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
35820 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20  iles may fail.  
35830 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78  Here is an.** ex
35840 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20  ample of how to 
35850 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b  do this using C+
35860 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f  + with the Windo
35870 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a  ws Runtime:.**.*
35880 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
35890 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a  re>.** LPCWSTR z
358a0 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a  Path = Windows::
358b0 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61  Storage::Applica
358c0 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e  tionData::Curren
358d0 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  t->.** &nbsp;   
358e0 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65    TemporaryFolde
358f0 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b  r->Path->Data();
35900 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75  .** char zPathBu
35910 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b  f&#91;MAX_PATH +
35920 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73   1&#93;;.** mems
35930 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20  et(zPathBuf, 0, 
35940 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29  sizeof(zPathBuf)
35950 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f  );.** WideCharTo
35960 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46  MultiByte(CP_UTF
35970 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c  8, 0, zPath, -1,
35980 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f   zPathBuf, sizeo
35990 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20  f(zPathBuf),.** 
359a0 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c  &nbsp;     NULL,
359b0 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74   NULL);.** sqlit
359c0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
359d0 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  y = sqlite3_mpri
359e0 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42  ntf("%s", zPathB
359f0 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  uf);.** </pre></
35a00 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53  blockquote>.*/.S
35a10 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
35a20 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
35a30 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
35a40 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
35a50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
35a60 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
35a70 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73  g Database Files
35a80 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
35a90 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
35aa0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
35ab0 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
35ac0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
35ad0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
35ae0 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
35af0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61  ), then all data
35b00 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70  base files.** sp
35b10 65 63 69 66 69 65 64 20 77 69 74 68 20 61 20 72  ecified with a r
35b20 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
35b30 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20   and created or 
35b40 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53  accessed by.** S
35b50 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
35b60 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64   a built-in wind
35b70 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ows [sqlite3_vfs
35b80 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20   | VFS] will be 
35b90 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65  assumed.** to be
35ba0 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61   relative to tha
35bb0 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e  t directory.)^ ^
35bc0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
35bd0 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   is a NULL.** po
35be0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
35bf0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
35c00 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
35c10 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  es specified.** 
35c20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
35c30 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c  pathname are rel
35c40 61 74 69 76 65 20 74 6f 20 74 68 65 20 63 75 72  ative to the cur
35c50 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a  rent directory.*
35c60 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73  * for the proces
35c70 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e  s.  Only the win
35c80 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75  dows VFS makes u
35c90 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61  se of this globa
35ca0 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69  l.** variable; i
35cb0 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20  t is ignored by 
35cc0 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a  the unix VFS..**
35cd0 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65  .** Changing the
35ce0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76   value of this v
35cf0 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20  ariable while a 
35d00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35d10 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63  ion is.** open c
35d20 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63  an result in a c
35d30 6f 72 72 75 70 74 20 64 61 74 61 62 61 73 65 2e  orrupt database.
35d40 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
35d50 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
35d60 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
35d70 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
35d80 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
35d90 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
35da0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
35db0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
35dc0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
35dd0 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
35de0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
35df0 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
35e00 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
35e10 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
35e20 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
35e30 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
35e40 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
35e50 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
35e60 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
35e70 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
35e80 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
35e90 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
35ea0 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
35eb0 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
35ec0 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
35ed0 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
35ee0 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
35ef0 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f  * ^The [data_sto
35f00 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
35f10 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
35f20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
35f30 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
35f40 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
35f50 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
35f60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
35f70 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
35f80 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f  ** the [data_sto
35f90 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
35fa0 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
35fb0 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
35fc0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
35fd0 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
35fe0 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
35ff0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
36000 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
36010 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
36020 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
36030 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
36040 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
36050 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
36060 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
36070 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
36080 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
36090 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
360a0 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
360b0 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
360c0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
360d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
360e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
360f0 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
36100 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f  of the [data_sto
36110 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
36120 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
36130 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  voided..*/.SQLIT
36140 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54  E_API SQLITE_EXT
36150 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
36160 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f 72 79  3_data_directory
36170 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36180 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f  F: Test For Auto
36190 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20  -Commit Mode.** 
361a0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
361b0 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
361c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
361d0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
361e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
361f0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
36200 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
36210 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
36220 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
36230 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
36240 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
36250 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63  ctively.  ^Autoc
36260 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
36270 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
36280 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
36290 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
362a0 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
362b0 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ent..** ^Autocom
362c0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
362d0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
362e0 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
362f0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
36300 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
36310 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
36320 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
36330 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
36340 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
36350 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
36360 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
36370 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
36380 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
36390 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
363a0 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
363b0 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
363c0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
363d0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
363e0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
363f0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
36400 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
36410 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
36420 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
36430 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
36440 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
36450 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
36460 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
36470 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
36480 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
36490 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
364a0 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
364b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
364c0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  ** connection wh
364d0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
364e0 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
364f0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
36500 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ue.** is undefin
36510 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
36520 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  I int sqlite3_ge
36530 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
36540 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
36550 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68  API3REF: Find Th
36560 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c  e Database Handl
36570 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20  e Of A Prepared 
36580 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
36590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
365a0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
365b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
365c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
365d0 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
365e0 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
365f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
36600 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74  ongs.  ^The [dat
36610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36620 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  ].** returned by
36630 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
36640 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b  le is the same [
36650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36660 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  ion].** that was
36670 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36680 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
36690 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
366a0 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
366b0 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
366c0 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
366d0 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
366e0 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
366f0 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49  t place..*/.SQLI
36700 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a  TE_API sqlite3 *
36710 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
36720 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
36730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36740 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 69  F: Return The Fi
36750 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74  lename For A Dat
36760 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
36770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36780 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28  te3_db_filename(
36790 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  D,N) interface r
367a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
367b0 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a   to a filename.*
367c0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
367d0 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20  h database N of 
367e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e  connection D.  ^
367f0 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  The main databas
36800 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68  e file.** has th
36810 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20  e name "main".  
36820 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61  If there is no a
36830 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
36840 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61   N on the databa
36850 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
36860 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61   D, or if databa
36870 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72  se N is a tempor
36880 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79  ary or in-memory
36890 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a   database, then.
368a0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
368b0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
368c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61  *.** ^The filena
368d0 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  me returned by t
368e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
368f0 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68  the output of th
36900 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61  e.** xFullPathna
36910 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  me method of the
36920 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68   [VFS].  ^In oth
36930 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69  er words, the fi
36940 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62  lename.** will b
36950 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  e an absolute pa
36960 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20  thname, even if 
36970 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65  the filename use
36980 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65  d.** to open the
36990 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e   database origin
369a0 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f  ally was a URI o
369b0 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e  r relative pathn
369c0 61 6d 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ame..*/.SQLITE_A
369d0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
369e0 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61  qlite3_db_filena
369f0 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  me(sqlite3 *db, 
36a00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
36a10 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
36a20 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
36a30 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 69   if a database i
36a40 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a  s read-only.**.*
36a50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
36a60 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20  b_readonly(D,N) 
36a70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36a80 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61 62  s 1 if the datab
36a90 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e  ase N.** of conn
36aa0 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61 64  ection D is read
36ab0 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 69  -only, 0 if it i
36ac0 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f 72  s read/write, or
36ad0 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a   -1 if N is not.
36ae0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
36af0 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e   database on con
36b00 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53 51  nection D..*/.SQ
36b10 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
36b20 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79  ite3_db_readonly
36b30 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
36b40 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
36b50 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
36b60 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
36b70 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
36b80 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ement.**.** ^Thi
36b90 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
36ba0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
36bb0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
36bc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
36bd0 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
36be0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
36bf0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36c00 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49  ection] pDb.  ^I
36c10 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a  f pStmt is NULL.
36c20 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74  ** then this int
36c30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
36c40 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
36c50 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73  first prepared s
36c60 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f  tatement.** asso
36c70 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
36c80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36c90 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f  ion pDb.  ^If no
36ca0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36cb0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
36cc0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
36cd0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
36ce0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
36cf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74  ..**.** The [dat
36d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36d10 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61  ] pointer D in a
36d20 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
36d30 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
36d40 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20  ,S)] must refer 
36d50 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  to an open datab
36d60 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
36d70 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75  n and in particu
36d80 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  lar must not be 
36d90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
36da0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
36db0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
36dc0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
36dd0 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
36de0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
36df0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36e00 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
36e10 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
36e20 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
36e30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36e40 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
36e50 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
36e60 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
36e70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36e80 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
36e90 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
36ea0 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d  s [COMMIT | comm
36eb0 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20  itted]..** ^Any 
36ec0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
36ed0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
36ee0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
36ef0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
36f00 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
36f10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
36f20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
36f30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
36f40 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
36f50 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
36f60 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
36f70 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
36f80 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
36f90 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
36fa0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65  ROLLBACK | rolle
36fb0 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79  d back]..** ^Any
36fc0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
36fd0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
36fe0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c   to sqlite3_roll
36ff0 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  back_hook().** f
37000 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
37010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37020 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
37030 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75  * ^The pArg argu
37040 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
37050 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
37060 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74  llback..** ^If t
37070 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
37080 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
37090 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
370a0 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
370b0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
370c0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
370d0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
370e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
370f0 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61  it_hook(D,C,P) a
37100 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  nd sqlite3_rollb
37110 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ack_hook(D,C,P) 
37120 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
37130 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65  urn the P argume
37140 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
37150 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65  ious call of the
37160 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
37170 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
37180 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37190 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
371a0 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
371b0 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75  call for each fu
371c0 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a  nction on D..**.
371d0 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e  ** The commit an
371e0 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  d rollback hook 
371f0 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f  callbacks are no
37200 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20  t reentrant..** 
37210 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
37220 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
37230 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
37240 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
37250 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
37260 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
37270 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
37280 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
37290 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
372a0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
372b0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
372c0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
372d0 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
372e0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
372f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
37300 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
37310 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
37320 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
37330 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
37340 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
37350 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  that running any
37360 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65   other SQL state
37370 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67  ments, including
37380 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
37390 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79  ts,.** or merely
373a0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
373b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
373c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
373d0 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79  p()] will modify
373e0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
373f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
37400 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
37410 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
37420 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
37430 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
37440 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
37450 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
37460 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
37470 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
37480 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
37490 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
374a0 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
374b0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
374c0 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
374d0 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
374e0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
374f0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
37500 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
37510 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
37520 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
37530 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
37540 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
37550 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
37560 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
37570 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
37580 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
37590 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
375a0 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
375b0 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
375c0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
375d0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
375e0 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
375f0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
37600 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
37610 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
37620 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
37630 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
37640 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
37650 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
37660 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
37670 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
37680 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
37690 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
376a0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
376b0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
376c0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
376d0 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
376e0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
376f0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
37700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37710 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
37720 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
37730 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
37740 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
37750 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
37760 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
37770 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
37780 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
37790 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
377a0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
377b0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
377c0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
377d0 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
377e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
377f0 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
37800 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
37810 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
37820 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
37830 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  e_hook() interfa
37840 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
37850 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
37860 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
37870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37880 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  n] identified by
37890 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
378a0 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ent.** to be inv
378b0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
378c0 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
378d0 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
378e0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ted..** ^Any cal
378f0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
37900 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
37910 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
37920 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
37930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37940 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
37950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
37960 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
37970 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
37980 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
37990 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77  ke when a.** row
379a0 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
379b0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
379c0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
379d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
379e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
379f0 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
37a00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
37a10 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
37a20 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65  ok()..** ^The se
37a30 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72  cond callback ar
37a40 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
37a50 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
37a60 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
37a70 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
37a80 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64  _UPDATE], depend
37a90 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
37aa0 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
37ab0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
37ac0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
37ad0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
37ae0 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  d fourth argumen
37af0 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
37b00 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
37b10 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ers to the.** da
37b20 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65  tabase and table
37b30 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   name containing
37b40 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f   the affected ro
37b50 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c  w..** ^The final
37b60 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
37b70 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69  ter is the [rowi
37b80 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  d] of the row..*
37b90 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f  * ^In the case o
37ba0 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
37bb0 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  s is the [rowid]
37bc0 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
37bd0 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
37be0 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74  *.** ^(The updat
37bf0 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
37c00 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
37c10 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
37c20 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
37c30 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
37c40 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
37c50 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a  _sequence).)^.**
37c60 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72  .** ^In the curr
37c70 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
37c80 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68  on, the update h
37c90 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e  ook.** is not in
37ca0 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69  voked when dupli
37cb0 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20  cation rows are 
37cc0 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20  deleted because 
37cd0 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e  of an.** [ON CON
37ce0 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c  FLICT | ON CONFL
37cf0 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61  ICT REPLACE] cla
37d00 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68  use.  ^Nor is th
37d10 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
37d20 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f   invoked when ro
37d30 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75  ws are deleted u
37d40 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61  sing the [trunca
37d50 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
37d60 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69  ..** The excepti
37d70 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74  ons defined in t
37d80 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69  his paragraph mi
37d90 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20  ght change in a 
37da0 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
37db0 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
37dc0 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  ** The update ho
37dd0 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ok implementatio
37de0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
37df0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
37e00 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
37e10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37e20 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
37e30 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
37e40 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
37e50 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
37e60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37e70 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
37e80 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
37e90 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
37ea0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
37eb0 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
37ec0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
37ed0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a  e update hook..*
37ee0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
37ef0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
37f00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
37f10 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
37f20 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
37f30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37f40 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
37f50 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
37f60 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
37f70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37f80 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37f90 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a  D,C,P) function.
37fa0 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ** returns the P
37fb0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
37fc0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
37fd0 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
37fe0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37ff0 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
38000 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
38010 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a  t call on D..**.
38020 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
38030 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
38040 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c  hook()] and [sql
38050 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
38060 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ok()].** interfa
38070 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ces..*/.SQLITE_A
38080 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
38090 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
380a0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
380b0 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
380c0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
380d0 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
380e0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
380f0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
38100 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
38110 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
38120 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a 2a  Pager Cache.**.*
38130 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
38140 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
38150 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
38160 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
38170 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
38180 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
38190 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
381a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
381b0 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
381c0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
381d0 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
381e0 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
381f0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
38200 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
38210 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
38220 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e  ment is false.)^
38230 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68  .**.** ^Cache sh
38240 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
38250 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
38260 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
38270 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
38280 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
38290 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
382a0 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
382b0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
382c0 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
382d0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
382e0 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
382f0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
38300 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63  .**.** ^(The cac
38310 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
38320 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
38330 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
38340 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
38350 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
38360 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
38370 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
38380 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
38390 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
383a0 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
383b0 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
383c0 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
383d0 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
383e0 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
383f0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
38400 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a  re opened.)^.**.
38410 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
38420 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
38430 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
38440 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
38450 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
38460 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
38470 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  An [error code] 
38480 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
38490 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rwise.)^.**.** ^
384a0 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
384b0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
384c0 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
384d0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
384e0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
384f0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
38500 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
38510 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
38520 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
38530 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
38540 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
38550 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
38560 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
38570 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54  e Mode].*/.SQLIT
38580 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
38590 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
385a0 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
385b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74  ** CAPI3REF: Att
385c0 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
385d0 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e  p Memory.**.** ^
385e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
385f0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74  ase_memory() int
38600 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
38610 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a  to free N bytes.
38620 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  ** of heap memor
38630 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
38640 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  g non-essential 
38650 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
38660 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68  ns.** held by th
38670 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
38680 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65  ry.   Memory use
38690 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  d to cache datab
386a0 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20  ase.** pages to 
386b0 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
386c0 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  nce is an exampl
386d0 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  e of non-essenti
386e0 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73  al memory..** ^s
386f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
38700 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
38710 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
38720 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
38730 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
38740 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
38750 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
38760 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a  nt requested..**
38770 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
38780 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
38790 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f  outine is a no-o
387a0 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f  p returning zero
387b0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
387c0 20 6e 6f 74 20