System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact fd2f6fc08b9bedc2cef32bf2309b6773940fb0ff:


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 50 72 6f 76 69 64 65 20 74 68 65 20 61 62  * Provide the ab
06b0: 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 64  ility to overrid
06c0: 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 72  e linkage featur
06d0: 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66  es of the interf
06e0: 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ace..*/.#ifndef 
06f0: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20  SQLITE_EXTERN.# 
0700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
0710: 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64  TERN extern.#end
0720: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0730: 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53  E_API.# define S
0740: 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66  QLITE_API.#endif
0750: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
0760: 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 53  CDECL.# define S
0770: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64  QLITE_CDECL.#end
0780: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0790: 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 69  E_STDCALL.# defi
07a0: 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  ne SQLITE_STDCAL
07b0: 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  L.#endif../*.** 
07c0: 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72  These no-op macr
07d0: 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 66  os are used in f
07e0: 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63  ront of interfac
07f0: 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65  es to mark those
0800: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
0810: 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 61  s either depreca
0820: 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e  ted or experimen
0830: 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63  tal.  New applic
0840: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
0850: 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 61   not use depreca
0860: 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d  ted interfaces -
0870: 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f 72   they are suppor
0880: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ted for backward
0890: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  s.** compatibili
08a0: 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  ty only.  Applic
08b0: 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68  ation writers sh
08c0: 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 68  ould be aware th
08d0: 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74  at.** experiment
08e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
08f0: 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  e subject to cha
0900: 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c  nge in point rel
0910: 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eases..**.** The
0920: 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74  se macros used t
0930: 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72  o resolve to var
0940: 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f  ious kinds of co
0950: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61  mpiler magic tha
0960: 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72  t.** would gener
0970: 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73  ate warning mess
0980: 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 77  ages when they w
0990: 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 74  ere used.  But t
09a0: 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20  hat.** compiler 
09b0: 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 67  magic ended up g
09c0: 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 61  enerating such a
09d0: 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72   flurry of bug r
09e0: 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77  eports.** that w
09f0: 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20  e have taken it 
0a00: 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65  all out and gone
0a10: 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73   back to using s
0a20: 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61  imple.** noop ma
0a30: 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  cros..*/.#define
0a40: 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
0a50: 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  ED.#define SQLIT
0a60: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a  E_EXPERIMENTAL..
0a70: 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65  /*.** Ensure the
0a80: 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20  se symbols were 
0a90: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73  not defined by s
0aa0: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61  ome previous hea
0ab0: 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66  der file..*/.#if
0ac0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0ad0: 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  ON.# undef SQLIT
0ae0: 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66  E_VERSION.#endif
0af0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56  .#ifdef SQLITE_V
0b00: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20  ERSION_NUMBER.# 
0b10: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  undef SQLITE_VER
0b20: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64  SION_NUMBER.#end
0b30: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
0b40: 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
0b50: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
0b60: 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e   Numbers.**.** ^
0b70: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52  (The [SQLITE_VER
0b80: 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65  SION] C preproce
0b90: 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68  ssor macro in th
0ba0: 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64  e sqlite3.h head
0bb0: 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20  er.** evaluates 
0bc0: 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
0bd0: 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20  ral that is the 
0be0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69  SQLite version i
0bf0: 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20  n the.** format 
0c00: 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20  "X.Y.Z" where X 
0c10: 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72  is the major ver
0c20: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77  sion number (alw
0c30: 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c  ays 3 for.** SQL
0c40: 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 74  ite3) and Y is t
0c50: 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e  he minor version
0c60: 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73   number and Z is
0c70: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d   the release num
0c80: 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20  ber.)^.** ^(The 
0c90: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
0ca0: 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f  NUMBER] C prepro
0cb0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73  cessor macro res
0cc0: 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65  olves to an inte
0cd0: 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ger.** with the 
0ce0: 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30  value (X*1000000
0cf0: 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77   + Y*1000 + Z) w
0d00: 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a  here X, Y, and Z
0d10: 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   are the same.**
0d20: 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e   numbers used in
0d30: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0d40: 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ].)^.** The SQLI
0d50: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0d60: 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20  R for any given 
0d70: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
0d80: 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62  e will also.** b
0d90: 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
0da0: 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77  e release from w
0db0: 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 76  hich it is deriv
0dc0: 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 69  ed.  Either Y wi
0dd0: 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f  ll.** be held co
0de0: 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c  nstant and Z wil
0df0: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64  l be incremented
0e00: 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20   or else Y will 
0e10: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a  be incremented.*
0e20: 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20  * and Z will be 
0e30: 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a  reset to zero..*
0e40: 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69  *.** Since versi
0e50: 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74  on 3.6.18, SQLit
0e60: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61  e source code ha
0e70: 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e  s been stored in
0e80: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
0e90: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73  "http://www.foss
0ea0: 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73  il-scm.org/">Fos
0eb0: 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  sil configuratio
0ec0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20  n management.** 
0ed0: 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68  system</a>.  ^Th
0ee0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ef0: 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74  ID macro evaluat
0f00: 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e  es to.** a strin
0f10: 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69  g which identifi
0f20: 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  es a particular 
0f30: 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69  check-in of SQLi
0f40: 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73  te.** within its
0f50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0f60: 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d  anagement system
0f70: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0f80: 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69  OURCE_ID.** stri
0f90: 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ng contains the 
0fa0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66  date and time of
0fb0: 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55   the check-in (U
0fc0: 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a  TC) and an SHA1.
0fd0: 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 65  ** hash of the e
0fe0: 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 65  ntire source tre
0ff0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
1000: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1010: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1020: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1030: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
1040: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
1050: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
1060: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1070: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1080: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
1090: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
10a0: 20 20 20 20 22 33 2e 38 2e 31 30 22 0a 23 64 65      "3.8.10".#de
10b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
10c0: 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 38 30  ION_NUMBER 30080
10d0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
10e0: 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20  E_SOURCE_ID     
10f0: 20 22 32 30 31 35 2d 30 35 2d 30 35 20 31 38 3a   "2015-05-05 18:
1100: 35 32 3a 35 34 20 30 34 61 66 61 33 66 65 62 65  52:54 04afa3febe
1110: 65 33 32 38 35 34 66 62 62 30 39 65 66 38 64 34  e32854fbb09ef8d4
1120: 66 66 66 66 64 34 33 32 31 31 39 37 31 36 22 0a  ffffd432119716".
1130: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1140: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1150: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72  y Version Number
1160: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
1170: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20  qlite3_version, 
1180: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1190: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
11a0: 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20  erfaces provide 
11b0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
11c0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
11d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a  ITE_VERSION],.**
11e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
11f0: 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53  _NUMBER], and [S
1200: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1210: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1220: 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72  macros.** but ar
1230: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1240: 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e  h the library in
1250: 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61  stead of the hea
1260: 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75  der file.  ^(Cau
1270: 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d  tious.** program
1280: 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75  mers might inclu
1290: 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
12a0: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20  ements in their 
12b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a  application to.*
12c0: 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61  * verify that va
12d0: 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
12e0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
12f0: 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72  s match the macr
1300: 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61  os in.** the hea
1310: 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e  der, and thus in
1320: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70  sure that the ap
1330: 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  plication is.** 
1340: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61  compiled with ma
1350: 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61  tching library a
1360: 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e  nd header files.
1370: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1380: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65  te><pre>.** asse
1390: 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  rt( sqlite3_libv
13a0: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d  ersion_number()=
13b0: 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  =SQLITE_VERSION_
13c0: 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73  NUMBER );.** ass
13d0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
13e0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53  te3_sourceid(),S
13f0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29  QLITE_SOURCE_ID)
1400: 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  ==0 );.** assert
1410: 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33  ( strcmp(sqlite3
1420: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51  _libversion(),SQ
1430: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30  LITE_VERSION)==0
1440: 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   );.** </pre></b
1450: 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
1460: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1470: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1480: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69   constant contai
1490: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b  ns the text of [
14a0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a  SQLITE_VERSION].
14b0: 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20  ** macro.  ^The 
14c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
14d0: 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  on() function re
14e0: 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
14f0: 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65  to the.** to the
1500: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1510: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1520: 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
1530: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a  _libversion().**
1540: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f   function is pro
1550: 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  vided for use in
1560: 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20   DLLs since DLL 
1570: 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f  users usually do
1580: 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72   not have.** dir
1590: 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74  ect access to st
15a0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77  ring constants w
15b0: 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20  ithin the DLL.  
15c0: 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
15d0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
15e0: 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  r() function ret
15f0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
1600: 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c  equal to.** [SQL
1610: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1620: 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ER].  ^The sqlit
1630: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75  e3_sourceid() fu
1640: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a  nction returns .
1650: 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
1660: 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  a string constan
1670: 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73  t whose value is
1680: 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65   the same as the
1690: 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55   .** [SQLITE_SOU
16a0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
16b0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a  cessor macro..**
16c0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
16d0: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
16e0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
16f0: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51  rce_id()]..*/.SQ
1700: 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
1710: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
1720: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
1730: 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  n[];.SQLITE_API 
1740: 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
1750: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1760: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f  e3_libversion(vo
1770: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
1780: 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
1790: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
17a0: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
17b0: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
17c0: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
17d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
17e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29  ion_number(void)
17f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1800: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1810: 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20  ary Compilation 
1820: 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74  Options Diagnost
1830: 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ics.**.** ^The s
1840: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1850: 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63  tion_used() func
1860: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f  tion returns 0 o
1870: 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69  r 1 .** indicati
1880: 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73  ng whether the s
1890: 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20  pecified option 
18a0: 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a  was defined at .
18b0: 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  ** compile time.
18c0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70    ^The SQLITE_ p
18d0: 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69  refix may be omi
18e0: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a  tted from the .*
18f0: 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61  * option name pa
1900: 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ssed to sqlite3_
1910: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1920: 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  ed().  .**.** ^T
1930: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1940: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66  leoption_get() f
1950: 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69  unction allows i
1960: 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72  terating.** over
1970: 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74   the list of opt
1980: 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64  ions that were d
1990: 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c  efined at compil
19a0: 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74  e time by.** ret
19b0: 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20  urning the N-th 
19c0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74  compile time opt
19d0: 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66  ion string.  ^If
19e0: 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
19f0: 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ge,.** sqlite3_c
1a00: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1a10: 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
1a20: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
1a30: 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65   SQLITE_ .** pre
1a40: 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66  fix is omitted f
1a50: 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20  rom any strings 
1a60: 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20  returned by .** 
1a70: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1a80: 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a  ption_get()..**.
1a90: 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20  ** ^Support for 
1aa0: 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66  the diagnostic f
1ab0: 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33  unctions sqlite3
1ac0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1ad0: 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c  sed().** and sql
1ae0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1af0: 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20  on_get() may be 
1b00: 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69  omitted by speci
1b10: 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53  fying the .** [S
1b20: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
1b30: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20  LEOPTION_DIAGS] 
1b40: 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c  option at compil
1b50: 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e time..**.** Se
1b60: 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63  e also: SQL func
1b70: 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f  tions [sqlite_co
1b80: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1b90: 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1ba0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1bb0: 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20  _get()] and the 
1bc0: 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73  [compile_options
1bd0: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66   pragma]..*/.#if
1be0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
1bf0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1c00: 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20  IAGS.SQLITE_API 
1c10: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1c20: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  LL sqlite3_compi
1c30: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1c40: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1c50: 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  me);.SQLITE_API 
1c60: 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
1c70: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1c80: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c90: 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e  _get(int N);.#en
1ca0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
1cb0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
1cc0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
1cd0: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
1ce0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1cf0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1d00: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1d10: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1d20: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1d30: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1d40: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
1d50: 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a  tted due to the.
1d60: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
1d70: 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  DSAFE] compile-t
1d80: 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67  ime option being
1d90: 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a   set to 0..**.**
1da0: 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63   SQLite can be c
1db0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20  ompiled with or 
1dc0: 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e  without mutexes.
1dd0: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53    When.** the [S
1de0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1df0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1e00: 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32   macro is 1 or 2
1e10: 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  , mutexes.** are
1e20: 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c   enabled and SQL
1e30: 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ite is threadsaf
1e40: 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20  e.  When the.** 
1e50: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1e60: 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20  FE] macro is 0, 
1e70: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20  .** the mutexes 
1e80: 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69  are omitted.  Wi
1e90: 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65  thout the mutexe
1ea0: 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66  s, it is not saf
1eb0: 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69  e.** to use SQLi
1ec0: 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20  te concurrently 
1ed0: 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f  from more than o
1ee0: 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ne thread..**.**
1ef0: 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65   Enabling mutexe
1f00: 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75  s incurs a measu
1f10: 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63  rable performanc
1f20: 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f  e penalty..** So
1f30: 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20   if speed is of 
1f40: 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63  utmost importanc
1f50: 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73  e, it makes sens
1f60: 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e to disable.** 
1f70: 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75  the mutexes.  Bu
1f80: 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61  t for maximum sa
1f90: 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68  fety, mutexes sh
1fa0: 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e  ould be enabled.
1fb0: 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1fc0: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72   behavior is for
1fd0: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65   mutexes to be e
1fe0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  nabled..**.** Th
1ff0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
2000: 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61   be used by an a
2010: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61  pplication to ma
2020: 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65  ke sure that the
2030: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  .** version of S
2040: 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73  QLite that it is
2050: 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74   linking against
2060: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
2070: 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65  th.** the desire
2080: 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65  d setting of the
2090: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
20a0: 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  AFE] macro..**.*
20b0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
20c0: 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e   only reports on
20d0: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
20e0: 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a  e mutex setting.
20f0: 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
2100: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c  E_THREADSAFE] fl
2110: 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ag.  If SQLite i
2120: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
2130: 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  ** SQLITE_THREAD
2140: 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65  SAFE=1 or =2 the
2150: 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e  n mutexes are en
2160: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2170: 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66   but.** can be f
2180: 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c  ully or partiall
2190: 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  y disabled using
21a0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
21b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a  te3_config()].**
21c0: 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20   with the verbs 
21d0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
21e0: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53  INGLETHREAD], [S
21f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
2200: 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72  TITHREAD],.** or
2210: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2220: 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28  SERIALIZED].  ^(
2230: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
2240: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
2250: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
2260: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2270: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2280: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2290: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
22a0: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
22b0: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
22c0: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
22d0: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
22e0: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
22f0: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2300: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
2310: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2320: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
2330: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
2340: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
2350: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
2360: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2370: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2380: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2390: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53  nformation..*/.S
23a0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
23b0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
23c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
23d0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
23e0: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
23f0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2400: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2410: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2420: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2430: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2440: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2450: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
2460: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2470: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
2480: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
2490: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
24a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
24b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
24c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
24d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
24e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
24f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2500: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2510: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2530: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2540: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2550: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
2560: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
2570: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2580: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
2590: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
25a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
25b0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
25c0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
25d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
25f0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2600: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2610: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2620: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2630: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2640: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2650: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
2660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2670: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
2680: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
2690: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
26a0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
26b0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
26c0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
26d0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
26e0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
26f0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2700: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2710: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2720: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2730: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2740: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2750: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
2760: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
2770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2780: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2790: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
27a0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
27b0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
27c0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
27d0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
27e0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
27f0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2800: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2810: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2820: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2830: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2840: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2850: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
2860: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
2870: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
2880: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
2890: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
28a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
28b0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
28c0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
28d0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
28e0: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
28f0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2900: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2910: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2920: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2930: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2940: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2950: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2960: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2970: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
2980: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
2990: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69  nt64;.#elif defi
29a0: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c  ned(_MSC_VER) ||
29b0: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41   defined(__BORLA
29c0: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66  NDC__).  typedef
29d0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
29e0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
29f0: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36   unsigned __int6
2a00: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  4 sqlite_uint64;
2a10: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66  .#else.  typedef
2a20: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2a30: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2a40: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2a50: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
2a60: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e  lite_uint64;.#en
2a70: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69  dif.typedef sqli
2a80: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  te_int64 sqlite3
2a90: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20  _int64;.typedef 
2aa0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71  sqlite_uint64 sq
2ab0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f  lite3_uint64;../
2ac0: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e  *.** If compilin
2ad0: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f  g for a processo
2ae0: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f  r that lacks flo
2af0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70  ating point supp
2b00: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75  ort,.** substitu
2b10: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66  te integer for f
2b20: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a  loating-point..*
2b30: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
2b40: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
2b50: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75  INT.# define dou
2b60: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ble sqlite3_int6
2b70: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
2b80: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e  CAPI3REF: Closin
2b90: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  g A Database Con
2ba0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52  nection.** DESTR
2bb0: 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a  UCTOR: sqlite3.*
2bc0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bd0: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
2be0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2bf0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
2c00: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72  structors.** for
2c10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2c20: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73  bject..** ^Calls
2c30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   to sqlite3_clos
2c40: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2c50: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72  close_v2() retur
2c60: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  n [SQLITE_OK] if
2c70: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63  ] object is succ
2c90: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ca0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2cb0: 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63  iated.** resourc
2cc0: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  es are deallocat
2cd0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
2ce0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2cf0: 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61  ction is associa
2d00: 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  ted with unfinal
2d10: 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a  ized prepared.**
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75   statements or u
2d30: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2d40: 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73  3_backup objects
2d50: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c   then sqlite3_cl
2d60: 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65  ose().** will le
2d70: 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ave the database
2d80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
2d90: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
2da0: 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49  ITE_BUSY]..** ^I
2db0: 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  f sqlite3_close_
2dc0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  v2() is called w
2dd0: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20  ith unfinalized 
2de0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2df0: 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e  nts.** and/or un
2e00: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2e10: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2e20: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2e30: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2e40: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2e50: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2e60: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2e70: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2e80: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2e90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ea0: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2eb0: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2ec0: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2ed0: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2ee0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2ef0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2f00: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2f10: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2f20: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2f30: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2f40: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2f50: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2f60: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2f70: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2f80: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2f90: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2fa0: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2fb0: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2fc0: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2fd0: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2fe0: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2ff0: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
3000: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
3010: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
3020: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
3030: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
3040: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
3050: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
3060: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
3070: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
3080: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
3090: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
30a0: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
30b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
30c0: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
30d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30e0: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
30f0: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
3100: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
3110: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
3120: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
3130: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
3140: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
3150: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b  hen it returns [
3160: 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74  SQLITE_OK] and t
3170: 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  he deallocation.
3180: 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20  ** of resources 
3190: 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  is deferred unti
31a0: 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  l all [prepared 
31b0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
31c0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20  OB handles],.** 
31d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  and [sqlite3_bac
31e0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65  kup] objects are
31f0: 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e   also destroyed.
3200: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73  .**.** ^If an [s
3210: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69  qlite3] object i
3220: 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c  s destroyed whil
3230: 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  e a transaction 
3240: 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20  is open,.** the 
3250: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61  transaction is a
3260: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
3270: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
3280: 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20  The C parameter 
3290: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
32a0: 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  e(C)] and [sqlit
32b0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a  e3_close_v2(C)].
32c0: 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
32d0: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
32e0: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
32f0: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
3300: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
3310: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
3320: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
3330: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
3340: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
3350: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
3360: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
3370: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
3380: 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73  te3_close() or s
3390: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
33a0: 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  ) with a NULL po
33b0: 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  inter.** argumen
33c0: 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  t is a harmless 
33d0: 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45  no-op..*/.SQLITE
33e0: 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33f0: 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
3400: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b  close(sqlite3*);
3410: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
3420: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
3430: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
3440: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
3450: 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61  * The type for a
3460: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3470: 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c  on..** This is l
3480: 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63  egacy and deprec
3490: 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63  ated.  It is inc
34a0: 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  luded for histor
34b0: 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ical.** compatib
34c0: 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74  ility and is not
34d0: 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a   documented..*/.
34e0: 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71  typedef int (*sq
34f0: 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28  lite3_callback)(
3500: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
3510: 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a  , char**);../*.*
3520: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d  * CAPI3REF: One-
3530: 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75  Step Query Execu
3540: 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a  tion Interface.*
3550: 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
3560: 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
3570: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
3580: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
3590: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
35a0: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
35b0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
35c0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
35d0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
35e0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
35f0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
3600: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
3610: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
3620: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
3630: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3640: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3650: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3660: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3670: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3680: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3690: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
36a0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
36b0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
36c0: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
36d0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
36e0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
36f0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
3700: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
3710: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
3720: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
3730: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3740: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3750: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3760: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3770: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3780: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3790: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
37a0: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
37b0: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
37c0: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
37d0: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
37e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
37f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3800: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
3810: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
3820: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
3830: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3840: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3850: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3860: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3870: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3880: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3890: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
38a0: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
38b0: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
38c0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
38d0: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
38e0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
38f0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
3900: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
3910: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
3920: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
3930: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3940: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3950: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3960: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3970: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3980: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3990: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39a0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
39b0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
39c0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
39d0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
39e0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
39f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
3a00: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
3a10: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
3a20: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
3a30: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3a40: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3a50: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3a60: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3a70: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3a80: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3a90: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3aa0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3ab0: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3ac0: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3ad0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
3ae0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
3af0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
3b00: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3b10: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3b20: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3b30: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3b40: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3b50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3b60: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3b70: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3b80: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3b90: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3ba0: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3bb0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3bc0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3bd0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
3be0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3bf0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
3c00: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
3c10: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
3c20: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
3c30: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3c40: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3c50: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3c60: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3c70: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3c80: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3c90: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3ca0: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3cb0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3cc0: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3cd0: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
3ce0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
3cf0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
3d00: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3d10: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3d20: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
3d30: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3d40: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3d50: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3d60: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3d70: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3d80: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3d90: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3da0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3db0: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3dc0: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3dd0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3de0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
3df0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
3e00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
3e10: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3e20: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
3e30: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3e40: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3e50: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3e60: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3e70: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3e80: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3e90: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3ea0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3eb0: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3ec0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3ed0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
3ee0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ef0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
3f00: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
3f10: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
3f20: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
3f30: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3f40: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3f50: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3f60: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3f70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3f80: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3f90: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3fa0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3fb0: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3fc0: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3fd0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3fe0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
3ff0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
4000: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
4010: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
4020: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
4030: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
4040: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
4050: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4060: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4070: 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61   close the [data
4080: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4090: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
40a0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
40b0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
40c0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
40d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
40e0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
40f0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
4100: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
4110: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
4120: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
4130: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
4140: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
4150: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
4160: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
4170: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
4180: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53  g..** </ul>.*/.S
4190: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
41a0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
41b0: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
41c0: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
41f0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
4200: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
4210: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4220: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
4230: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
4240: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
4250: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
4260: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
4270: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
4280: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
4290: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
42c0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
42d0: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
42e0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
4310: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
4320: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
4330: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
4340: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
4350: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
4360: 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d  nitions}.**.** M
4370: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
4380: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
4390: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
43a0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
43b0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
43c0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
43d0: 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  te success or fa
43e0: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  ilure..**.** New
43f0: 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79   error codes may
4400: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
4410: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
4420: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  SQLite..**.** Se
4430: 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65  e also: [extende
4440: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65  d result code de
4450: 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64  finitions].*/.#d
4460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20  efine SQLITE_OK 
4470: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
4480: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75   Successful resu
4490: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69  lt */./* beginni
44a0: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  ng-of-error-code
44b0: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
44c0: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20  ITE_ERROR       
44d0: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f   1   /* SQL erro
44e0: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74  r or missing dat
44f0: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
4500: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
4510: 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65       2   /* Inte
4520: 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72  rnal logic error
4530: 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64   in SQLite */.#d
4540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52  efine SQLITE_PER
4550: 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a  M         3   /*
4560: 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69   Access permissi
4570: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4580: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
4590: 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20  T        4   /* 
45a0: 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  Callback routine
45b0: 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62   requested an ab
45c0: 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ort */.#define S
45d0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20  QLITE_BUSY      
45e0: 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61     5   /* The da
45f0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c  tabase file is l
4600: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4610: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20   SQLITE_LOCKED  
4620: 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61       6   /* A ta
4630: 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  ble in the datab
4640: 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ase is locked */
4650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4660: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20  NOMEM        7  
4670: 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66   /* A malloc() f
4680: 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ailed */.#define
4690: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
46a0: 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65       8   /* Atte
46b0: 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72  mpt to write a r
46c0: 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65  eadonly database
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20  TE_INTERRUPT    
46f0: 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  9   /* Operation
4700: 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73   terminated by s
4710: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
4720: 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ()*/.#define SQL
4730: 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20  ITE_IOERR       
4740: 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e  10   /* Some kin
4750: 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72  d of disk I/O er
4760: 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a  ror occurred */.
4770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4780: 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20  ORRUPT     11   
4790: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
47a0: 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61  disk image is ma
47b0: 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69  lformed */.#defi
47c0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  ne SQLITE_NOTFOU
47d0: 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e  ND    12   /* Un
47e0: 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20  known opcode in 
47f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
4800: 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e  trol() */.#defin
4810: 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20  e SQLITE_FULL   
4820: 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73       13   /* Ins
4830: 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65  ertion failed be
4840: 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69  cause database i
4850: 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e  s full */.#defin
4860: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
4870: 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61  N    14   /* Una
4880: 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ble to open the 
4890: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20  PROTOCOL    15  
48c0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63   /* Database loc
48d0: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
4900: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
4910: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
4920: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
4930: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
4940: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
4950: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
4970: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
4980: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
4990: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
49a0: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
49b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
49c0: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
49d0: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
49e0: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
49f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4a00: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
4a10: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
4a20: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
4a30: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
4a40: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
4a50: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
4a60: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
4a70: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
4a80: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
4a90: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
4aa0: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
4ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4ac0: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
4ad0: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
4ae0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
4b00: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
4b10: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
4b20: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
4b30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b40: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
4b50: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
4b60: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
4b70: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
4b80: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4b90: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
4ba0: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
4bb0: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
4bc0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
4bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4be0: 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37  E_NOTICE      27
4bf0: 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69     /* Notificati
4c00: 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ons from sqlite3
4c10: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4c20: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
4c30: 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72       28   /* War
4c40: 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74  nings from sqlit
4c50: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c60: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
4c70: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
4c80: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4c90: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4ca0: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4cb0: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4cc0: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4cd0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4ce0: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4cf0: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4d00: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4d20: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4d30: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
4d40: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4d50: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4d60: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4d70: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4d80: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4d90: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4da0: 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65  n one of 30 inte
4db0: 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63  ger.** [result c
4dc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4dd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4de0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4df0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4e00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4e10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4e20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4e30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4e40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4e50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4e60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4e70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4e80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4e90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ea0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4eb0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4ec0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4ed0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4ee0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4ef0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4f00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4f10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4f20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4f30: 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64  s. These [extend
4f40: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
4f50: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20   are enabled or 
4f60: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61  disabled.** on a
4f70: 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f   per database co
4f80: 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75  nnection basis u
4f90: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
4fa0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
4fb0: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50  sult_codes()] AP
4fc0: 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65  I.  Or, the exte
4fd0: 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a  nded code for.**
4fe0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
4ff0: 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62   error can be ob
5000: 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  tained using.** 
5010: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
5020: 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f  d_errcode()]..*/
5030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5040: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5050: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5060: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5080: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5090: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50a0: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
50b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50c0: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
50d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50e0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5100: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
5110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5120: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
5130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5140: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5150: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5160: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5190: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51a0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
51c0: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
51d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51e0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
5200: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
5210: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5220: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5230: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5240: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5250: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5260: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5280: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
52c0: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
5300: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5340: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5380: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
53c0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
5400: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5440: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5540: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5580: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
55c0: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
5600: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54  SQLITE_IOERR_GET
5640: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28  TEMPPATH       (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5660: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  25<<8)).#define 
5670: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e  SQLITE_IOERR_CON
5680: 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28  VPATH          (
5690: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
56a0: 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  26<<8)).#define 
56b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
56c0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
56d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
56e0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
56f0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5700: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5710: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5720: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
5740: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
5750: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5760: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
5770: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5780: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5790: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
57a0: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
57b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
57c0: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
57d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
57e0: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
57f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5800: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
5810: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5820: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
5830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5840: 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54  CANTOPEN_CONVPAT
5850: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38  CANTOPEN | (4<<8
5870: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5880: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
5890: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
58a0: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
58b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58c0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
58d0: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
58e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
58f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5900: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
5910: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
5920: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5930: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5940: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5950: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28  ROLLBACK       (
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5970: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5980: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5990: 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20  Y_DBMOVED       
59a0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59b0: 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  Y | (4<<8)).#def
59c0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
59d0: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
59e0: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
59f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5a00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a10: 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20  AINT_CHECK      
5a20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a30: 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AINT | (1<<8)).#
5a40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48  NSTRAINT_COMMITH
5a60: 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  OOK   (SQLITE_CO
5a70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38  NSTRAINT | (2<<8
5a80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52  E_CONSTRAINT_FOR
5aa0: 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54  EIGNKEY   (SQLIT
5ab0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ac0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ad0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ae0: 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53  _FUNCTION     (S
5af0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b00: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5b10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b20: 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20  AINT_NOTNULL    
5b30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b40: 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23  AINT | (5<<8)).#
5b50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5b60: 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59  NSTRAINT_PRIMARY
5b70: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5b80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38  NSTRAINT | (6<<8
5b90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5ba0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49  E_CONSTRAINT_TRI
5bb0: 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54  GGER      (SQLIT
5bc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5bd0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
5be0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5bf0: 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53  _UNIQUE       (S
5c00: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c10: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
5c20: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c30: 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20  AINT_VTAB       
5c40: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c50: 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23  AINT | (9<<8)).#
5c60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5c70: 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20  NSTRAINT_ROWID  
5c80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5c90: 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38  NSTRAINT |(10<<8
5ca0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5cb0: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5cc0: 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54  _WAL      (SQLIT
5cd0: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38  E_NOTICE | (1<<8
5ce0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5cf0: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5d00: 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54  _ROLLBACK (SQLIT
5d10: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38  E_NOTICE | (2<<8
5d20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d30: 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e  E_WARNING_AUTOIN
5d40: 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54  DEX       (SQLIT
5d50: 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c  E_WARNING | (1<<
5d60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d70: 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20  TE_AUTH_USER    
5d80: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5d90: 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29  TE_AUTH | (1<<8)
5da0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5db0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5dc0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5dd0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5de0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5df0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5e00: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5e10: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5e20: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5e30: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5e40: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5e50: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5e60: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5e70: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5e80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5e90: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5ea0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5eb0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ec0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5ee0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5ef0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5f00: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f10: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f30: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
5f40: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
5f50: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5f60: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f80: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5f90: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5fa0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5fd0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5fe0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6000: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
6010: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6020: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6040: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6050: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6060: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6070: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6090: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
60a0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
60b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
60c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
60f0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6130: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6140: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6160: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6170: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
6180: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61a0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
61b0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
61c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61e0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
61f0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
6200: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6220: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6230: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6240: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6260: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6270: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6280: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62a0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
62b0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
62c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
62d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
62e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62f0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
6300: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
6310: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6320: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6350: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6360: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6370: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6390: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
63a0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
63b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63e0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
63f0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
6400: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
6410: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6430: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6440: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6450: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
6460: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
6470: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6480: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
6490: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
64a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
64b0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
64c0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
64d0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
64e0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
64f0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
6500: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
6510: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6520: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6530: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6540: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6550: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6560: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
6570: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6580: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6590: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65a0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
65b0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
65c0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
65d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
65e0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
65f0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
6600: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
6610: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6620: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6630: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6640: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6650: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6660: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6670: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6680: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6690: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
66a0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
66b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
66c0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
66d0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
66e0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
66f0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
6700: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
6710: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6720: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6730: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6740: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6750: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6760: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6770: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6780: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6790: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
67a0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
67b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
67c0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
67d0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
67e0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
67f0: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
6800: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
6810: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6820: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6830: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6840: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6850: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
6860: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
6870: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
6880: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
6890: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
68a0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
68b0: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
68c0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
68d0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
68e0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
68f0: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
6900: 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  ag indicate that
6910: 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62   a file cannot b
6920: 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f  e deleted when o
6930: 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  pen.  The.** SQL
6940: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
6950: 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74  BLE flag indicat
6960: 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65  es that the file
6970: 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f   is on.** read-o
6980: 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61  nly media and ca
6990: 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
69a0: 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65  even by processe
69b0: 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74  s with.** elevat
69c0: 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a  ed privileges..*
69d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
69e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a00: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6a10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a20: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6a30: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6a40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6a50: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6a60: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6a70: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
6a80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6a90: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
6aa0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
6ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ac0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
6ad0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ae0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
6af0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6b00: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6b10: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6b20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b30: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
6b40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6b50: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
6b60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6b70: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6b80: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
6b90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ba0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
6bb0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
6bc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6bd0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6be0: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
6bf0: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6c00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6c10: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6c20: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6c40: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6c50: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6c60: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
6c70: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6c80: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
6c90: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
6ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6cb0: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20  P_IMMUTABLE     
6cc0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32           0x00002
6cd0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
6ce0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
6cf0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
6d00: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
6d10: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
6d20: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6d30: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
6d40: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
6d50: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
6d60: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6d70: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
6d80: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6d90: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
6da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6db0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
6dc0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
6dd0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
6de0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
6df0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
6e00: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
6e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6e20: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
6e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e40: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
6e50: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6e60: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
6e70: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
6e80: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6e90: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6ea0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6eb0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6ec0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6ed0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6ee0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6ef0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6f00: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6f10: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6f20: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6f30: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6f40: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6f50: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6f60: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6f70: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6f80: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6f90: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6fa0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6fb0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6fc0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
6fd0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
6fe0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
6ff0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
7000: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
7010: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
7020: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
7030: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
7040: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
7050: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
7060: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
7070: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
7080: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7090: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
70a0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
70b0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
70c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
70d0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
70e0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
70f0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
7100: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
7110: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
7120: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
7130: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
7140: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
7150: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
7160: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
7170: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
7180: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
7190: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
71a0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
71b0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
71c0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
71d0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
71e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
71f0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
7200: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7210: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7220: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7230: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7240: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7250: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
7260: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
7270: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
7280: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
7290: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
72a0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
72b0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
72c0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
72d0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
72e0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
72f0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
7300: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7310: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7320: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7330: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7340: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7350: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
7360: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
7370: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7380: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
7390: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
73a0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
73b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
73c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
73d0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
73e0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
73f0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7400: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7410: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7420: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7430: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7440: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7450: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
7460: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
7470: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
7480: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
7490: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
74a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
74b0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
74c0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
74d0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
74e0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
74f0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
7500: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7510: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7520: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7530: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7540: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7550: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
7560: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
7570: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
7580: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
7590: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
75a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
75b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
75c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
75d0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
75e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
75f0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
7600: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7610: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7620: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7630: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7640: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7650: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
7660: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
7670: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
7680: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7690: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
76a0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
76b0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
76c0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
76d0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
76e0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
76f0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7700: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7710: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7720: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7730: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7740: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7750: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
7760: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
7770: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
7780: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
7790: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
77a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
77b0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
77c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
77d0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
77e0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
77f0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7800: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7810: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7820: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7830: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7840: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7850: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
7860: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
7870: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
7880: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
7890: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
78a0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
78b0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
78c0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
78d0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
78e0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
78f0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7900: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7910: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7920: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7930: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7940: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7950: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
7960: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
7970: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
7980: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
7990: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
79a0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
79b0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
79c0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
79d0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
79e0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
79f0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7a00: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7a10: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7a20: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7a30: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7a40: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7a50: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7a60: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7a70: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7a80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
7a90: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
7aa0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7ab0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
7ac0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7ad0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7ae0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7af0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7b00: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b10: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7b20: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b30: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7b40: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7b50: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7b60: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7b70: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7b80: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
7b90: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
7ba0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
7bb0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
7bc0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
7bd0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
7be0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7bf0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7c00: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
7c10: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
7c20: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
7c30: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
7c40: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
7c50: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
7c60: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
7c70: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
7c80: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
7c90: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
7ca0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
7cb0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
7cc0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
7cd0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
7ce0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
7cf0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
7d00: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
7d10: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
7d20: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
7d30: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7d40: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7d50: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
7d60: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
7d70: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
7d80: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
7d90: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
7da0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
7db0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
7dc0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
7dd0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
7de0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
7df0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
7e00: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
7e10: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
7e20: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
7e30: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
7e40: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
7e50: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
7e60: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
7e70: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
7e80: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
7e90: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
7ea0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
7eb0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
7ec0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
7ed0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
7ee0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
7ef0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
7f00: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
7f10: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
7f20: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
7f30: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
7f40: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
7f50: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
7f60: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
7f70: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
7f80: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
7f90: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
7fa0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
7fb0: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
7fc0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
7fd0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
7fe0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
7ff0: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
8000: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
8010: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
8020: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8030: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
8040: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
8050: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
8060: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
8070: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
8080: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
8090: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
80a0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
80b0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
80c0: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
80d0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
80e0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
80f0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
8100: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8110: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8120: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8130: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8140: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
8150: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
8160: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8170: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
8180: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
8190: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
81a0: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
81b0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
81c0: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
81d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
81e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
81f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8200: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8210: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8220: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8230: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8240: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
8250: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8260: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
8270: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8280: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
8290: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
82b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
82c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
82d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
82f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8300: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8310: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8320: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8330: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  NTIAL].** </ul>.
8340: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
8350: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
8360: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8370: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
8380: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
8390: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
83a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
83b0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
83c0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
83d0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
83e0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
83f0: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
8400: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
8410: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
8420: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
8430: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
8440: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
8450: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8460: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
8470: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
8480: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
8490: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
84a0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
84b0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
84c0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
84d0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
84e0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
84f0: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
8500: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8510: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
8520: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
8530: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
8540: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
8550: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
8560: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
8570: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a  to xWrite()..**.
8580: 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65  ** If xRead() re
8590: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45  turns SQLITE_IOE
85a0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74  RR_SHORT_READ it
85b0: 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a   must also fill.
85c0: 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64  ** in the unread
85d0: 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65   portions of the
85e0: 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72   buffer with zer
85f0: 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a  os.  A VFS that.
8600: 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f  ** fails to zero
8610: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
8620: 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20  s might seem to 
8630: 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a  work.  However,.
8640: 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65  ** failure to ze
8650: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8660: 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ads will eventua
8670: 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64  lly lead to.** d
8680: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
8690: 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
86a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
86b0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
86c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
86d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
86e0: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
86f0: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
8700: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
8710: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8720: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
8730: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
8740: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8750: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8760: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
8770: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
8780: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
8790: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
87a0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
87b0: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
87c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
87d0: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
87e0: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
87f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8800: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
8810: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
8820: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8830: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
8840: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
8850: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8860: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8870: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
8880: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8890: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
88a0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
88b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
88c0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
88d0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
88e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
88f0: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
8900: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
8910: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
8920: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8930: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
8940: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
8950: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  ile*);.  /* Meth
8960: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8970: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8980: 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68  1 */.  int (*xSh
8990: 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  mMap)(sqlite3_fi
89a0: 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e  le*, int iPg, in
89b0: 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69  t pgsz, int, voi
89c0: 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20  d volatile**);. 
89d0: 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29   int (*xShmLock)
89e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
89f0: 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20  int offset, int 
8a00: 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  n, int flags);. 
8a10: 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72   void (*xShmBarr
8a20: 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ier)(sqlite3_fil
8a30: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
8a40: 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f  mUnmap)(sqlite3_
8a50: 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74  file*, int delet
8a60: 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74  eFlag);.  /* Met
8a70: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8a80: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8a90: 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46   2 */.  int (*xF
8aa0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8ab0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8ac0: 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41  64 iOfst, int iA
8ad0: 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a  mt, void **pp);.
8ae0: 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68    int (*xUnfetch
8af0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8b00: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8b10: 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a  Ofst, void *p);.
8b20: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8b30: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8b40: 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20   version 3 */.  
8b50: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
8b60: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
8b70: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
8b80: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
8b90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
8ba0: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
8bb0: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45  ol Opcodes.** KE
8bc0: 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f  YWORDS: {file co
8bd0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b  ntrol opcodes} {
8be0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8bf0: 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ode}.**.** These
8c00: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8c10: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
8c20: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
8c30: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
8c40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
8c50: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8c60: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
8c70: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8c80: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
8c90: 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce..**.** <ul>.*
8ca0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8cb0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d  CNTL_LOCKSTATE]]
8cc0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8cd0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
8ce0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8cf0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
8d00: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
8d10: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
8d20: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
8d30: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
8d40: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
8d50: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
8d60: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
8d70: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
8d80: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
8d90: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
8da0: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
8db0: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
8dc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
8dd0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
8de0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
8df0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
8e00: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
8e10: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
8e20: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
8e30: 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e  esting and is on
8e40: 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65  ly available whe
8e50: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53  n the SQLITE_TES
8e60: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
8e70: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  e option is used
8e80: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8e90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8ea0: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
8eb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8ec0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
8ed0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
8ee0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
8ef0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8f00: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8f10: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8f20: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8f30: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8f40: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8f50: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8f60: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8f70: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8f80: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8f90: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8fa0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
8fb0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
8fc0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
8fd0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
8fe0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
8ff0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
9000: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
9010: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
9020: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
9030: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9040: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
9050: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
9060: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9070: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
9080: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
9090: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
90a0: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
90b0: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
90c0: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
90d0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
90e0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
90f0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
9100: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
9110: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9120: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
9130: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
9140: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
9150: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
9160: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
9170: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
9180: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
9190: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
91a0: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
91b0: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
91c0: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
91d0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
91e0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
91f0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
9200: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
9210: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
9220: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
9230: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9240: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
9250: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9260: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
9270: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9280: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9290: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
92a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
92b0: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
92c0: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
92d0: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
92e0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
92f0: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
9300: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9310: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
9320: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
9330: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
9340: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9350: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
9360: 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65  ED]].** No longe
9370: 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  r in use..**.** 
9380: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9390: 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65  TL_SYNC]].** The
93a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
93b0: 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  YNC] opcode is g
93c0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
93d0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e  lly by SQLite an
93e0: 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65  d.** sent to the
93f0: 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79   VFS immediately
9400: 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e   before the xSyn
9410: 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  c method is invo
9420: 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61  ked on a.** data
9430: 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69  base file descri
9440: 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65  ptor. Or, if the
9450: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
9460: 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a   not invoked .**
9470: 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65   because the use
9480: 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64  r has configured
9490: 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a   SQLite with .**
94a0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
94b0: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
94c0: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
94d0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20  t is invoked in 
94e0: 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65  place .** of the
94f0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49   xSync method. I
9500: 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68  n most cases, th
9510: 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
9520: 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a  nt passed with.*
9530: 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  * this file-cont
9540: 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77  rol is NULL. How
9550: 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74  ever, if the dat
9560: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65  abase file is be
9570: 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73  ing synced.** as
9580: 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69   part of a multi
9590: 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74  -database commit
95a0: 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  , the argument p
95b0: 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74  oints to a nul-t
95c0: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
95d0: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
95e0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  he transactions 
95f0: 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66  master-journal f
9600: 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20  ile name. VFSes 
9610: 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20  that .** do not 
9620: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9630: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9640: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9650: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9660: 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  s .** should not
9670: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
9680: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
9690: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
96a0: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
96b0: 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20  .** disrupt the 
96c0: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
96d0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
96e0: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
96f0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9700: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9710: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9720: 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  O]].** The [SQLI
9730: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
9740: 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65  PHASETWO] opcode
9750: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9760: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9770: 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74  te.** and sent t
9780: 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20  o the VFS after 
9790: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61  a transaction ha
97a0: 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  s been committed
97b0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
97c0: 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64  but before the d
97d0: 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63  atabase is unloc
97e0: 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20  ked. VFSes that 
97f0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9800: 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c   signal.** shoul
9810: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9820: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9830: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
9840: 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b  ld not call.** [
9850: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9860: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9870: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9880: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
9890: 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69   the .** operati
98a0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
98b0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
98c0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
98d0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
98e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
98f0: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
9900: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9910: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9920: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9930: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
9940: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
9950: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
9960: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
9970: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
9980: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
9990: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
99a0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
99b0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
99c0: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
99d0: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
99e0: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
99f0: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
9a00: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
9a10: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
9a20: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
9a30: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
9a40: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
9a50: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
9a60: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
9a70: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
9a80: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
9a90: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
9aa0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
9ab0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
9ac0: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
9ad0: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
9ae0: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
9af0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
9b00: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
9b10: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
9b20: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
9b30: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
9b40: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
9b50: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
9b60: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
9b70: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
9b80: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
9b90: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
9ba0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
9bb0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
9bc0: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
9bd0: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
9be0: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
9bf0: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20  teger i the new 
9c00: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
9c10: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
9c20: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
9c30: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
9c40: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
9c50: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
9c60: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
9c70: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
9c80: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
9c90: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
9ca0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
9cb0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
9cc0: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
9cd0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
9ce0: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
9cf0: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
9d00: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
9d10: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
9d20: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
9d30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
9d40: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
9d50: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9d60: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
9d70: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9d80: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
9d90: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
9da0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65  [WAL | Write Ahe
9db0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
9dc0: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
9dd0: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
9de0: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
9df0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
9e00: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
9e10: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
9e20: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
9e30: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
9e40: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
9e50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
9e60: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
9e70: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
9e80: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
9e90: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
9ea0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
9eb0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
9ec0: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
9ed0: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
9ee0: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
9ef0: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
9f00: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
9f10: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
9f20: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
9f30: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
9f40: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
9f50: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
9f60: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
9f70: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
9f80: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9f90: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
9fa0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
9fb0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
9fc0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
9fd0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9fe0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9ff0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a000: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a010: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a020: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a030: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a040: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a050: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
a060: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a070: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
a080: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
a090: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a0a0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a0b0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a0c0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
a0d0: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
a0e0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a0f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a100: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a110: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a130: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a140: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a150: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a160: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a170: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
a180: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
a190: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
a1a0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
a1b0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
a1c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
a1d0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a1e0: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
a1f0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
a200: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
a210: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a220: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
a230: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a240: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
a250: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
a260: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
a270: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
a280: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
a290: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
a2a0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
a2b0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
a2c0: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
a2d0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
a2e0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
a2f0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
a300: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
a310: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
a320: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a330: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a340: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a350: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a360: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
a370: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
a380: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
a390: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
a3a0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
a3b0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
a3c0: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
a3d0: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
a3e0: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
a3f0: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
a400: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
a410: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
a420: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
a430: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
a440: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
a450: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
a460: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a470: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
a480: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a490: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
a4a0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
a4b0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
a4c0: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
a4d0: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
a4e0: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
a4f0: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
a500: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
a510: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
a520: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
a530: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
a540: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
a550: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
a560: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
a570: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
a580: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
a590: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
a5a0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
a5b0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
a5c0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
a5d0: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
a5e0: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
a5f0: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
a600: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
a610: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
a620: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
a630: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
a640: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
a650: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
a660: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
a670: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
a680: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
a690: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
a6a0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
a6b0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
a6c0: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
a6d0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
a6e0: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
a6f0: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
a700: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
a710: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
a720: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
a730: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a740: 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20  NTL_PRAGMA]].** 
a750: 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41  ^Whenever a [PRA
a760: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  GMA] statement i
a770: 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51  s parsed, an [SQ
a780: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a790: 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  A] .** file cont
a7a0: 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74  rol is sent to t
a7b0: 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33  he open [sqlite3
a7c0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f  _file] object co
a7d0: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74  rresponding.** t
a7e0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
a7f0: 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65  ile to which the
a800: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
a810: 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61  t refers. ^The a
a820: 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
a830: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a840: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a850: 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79  trol is an array
a860: 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20   of.** pointers 
a870: 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72  to strings (char
a880: 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65  **) in which the
a890: 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20   second element 
a8a0: 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20  of the array.** 
a8b0: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
a8c0: 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68  he pragma and th
a8d0: 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20  e third element 
a8e0: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
a8f0: 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61  to the.** pragma
a900: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
a910: 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72  pragma has no ar
a920: 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61  gument.  ^The ha
a930: 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20  ndler for an.** 
a940: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a950: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a960: 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  ol can optionall
a970: 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74  y make the first
a980: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74   element.** of t
a990: 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65  he char** argume
a9a0: 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  nt point to a st
a9b0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
a9c0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
a9d0: 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65  ntf()].** or the
a9e0: 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20   equivalent and 
a9f0: 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c  that string will
aa00: 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75   become the resu
aa10: 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  lt of the pragma
aa20: 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72   or.** the error
aa30: 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20   message if the 
aa40: 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49  pragma fails. ^I
aa50: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
aa60: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
aa70: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
aa80: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  rns [SQLITE_NOTF
aa90: 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d  OUND], then norm
aaa0: 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20  al .** [PRAGMA] 
aab0: 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69  processing conti
aac0: 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b  nues.  ^If the [
aad0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aae0: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
aaf0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
ab00: 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74  LITE_OK], then t
ab10: 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65  he parser assume
ab20: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46  s that the.** VF
ab30: 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68  S has handled th
ab40: 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20  e PRAGMA itself 
ab50: 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67  and the parser g
ab60: 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70  enerates a no-op
ab70: 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
ab80: 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74  tement if result
ab90: 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c   string is NULL,
aba0: 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e 73   or that returns
abb0: 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
abc0: 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  e result string 
abd0: 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  if the string is
abe0: 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49   non-NULL..** ^I
abf0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
ac00: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ac10: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
ac20: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
ac30: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
ac40: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
ac50: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
ac60: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
ac70: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
ac80: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
ac90: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
aca0: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
acb0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
acc0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
acd0: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
ace0: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
acf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ad00: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
ad10: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
ad20: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
ad30: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
ad40: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
ad50: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
ad60: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
ad70: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
ad80: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
ad90: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ada0: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
adb0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
adc0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
add0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
ade0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
adf0: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
ae00: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
ae10: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
ae20: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
ae30: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
ae40: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
ae50: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
ae60: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
ae70: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
ae80: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
ae90: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
aea0: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
aeb0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
aec0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
aed0: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
aee0: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
aef0: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
af00: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
af10: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
af20: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
af30: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
af40: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
af50: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
af60: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
af70: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
af80: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
af90: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
afa0: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
afb0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
afc0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
afd0: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
afe0: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
aff0: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
b000: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
b010: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
b020: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
b030: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
b040: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
b050: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b060: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
b070: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
b080: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
b090: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b0a0: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
b0b0: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
b0c0: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
b0d0: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
b0e0: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
b0f0: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
b100: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
b110: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
b120: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
b130: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
b140: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
b150: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
b160: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
b170: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
b180: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
b190: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
b1a0: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
b1b0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
b1c0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
b1d0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
b1e0: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
b1f0: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
b200: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
b210: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
b220: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
b230: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
b240: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
b250: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
b260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b270: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
b280: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b290: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
b2a0: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
b2b0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
b2c0: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b2d0: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b2e0: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b2f0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b300: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b310: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b320: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b330: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b340: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b350: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b360: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b370: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b380: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b390: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b3a0: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b3b0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b3c0: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b3d0: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b3e0: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b3f0: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b400: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b410: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b420: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b430: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b440: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b450: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b460: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b470: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b480: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b490: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b4a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b4b0: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b4c0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b4d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b4e0: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b4f0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b500: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b510: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b520: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b530: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b540: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b550: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b560: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b570: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b580: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
b590: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
b5a0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
b5b0: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
b5c0: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
b5d0: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
b5e0: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
b5f0: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
b600: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
b610: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
b620: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
b630: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
b640: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
b650: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b660: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
b670: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b680: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
b690: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
b6a0: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
b6b0: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
b6c0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
b6d0: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
b6e0: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
b6f0: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
b700: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
b710: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
b720: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
b730: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
b740: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
b750: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
b760: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
b770: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b780: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
b790: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b7a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
b7b0: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
b7c0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
b7d0: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
b7e0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
b7f0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
b800: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
b810: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
b820: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
b830: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
b840: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
b850: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
b860: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b870: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
b880: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
b890: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
b8a0: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
b8b0: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  fined..**.** <li
b8c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b8d0: 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54  WAL_BLOCK]].** T
b8e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b8f0: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61  _WAL_BLOCK] is a
b900: 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56   signal to the V
b910: 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 74  FS layer that it
b920: 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76   might.** be adv
b930: 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f  antageous to blo
b940: 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57  ck on the next W
b950: 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c  AL lock if the l
b960: 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64  ock is not immed
b970: 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61  iately.** availa
b980: 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75  ble.  The WAL su
b990: 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 74  bsystem issues t
b9a0: 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e  his signal durin
b9b0: 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d  g rare.** circum
b9c0: 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72  stances in order
b9d0: 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65   to fix a proble
b9e0: 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 20  m with priority 
b9f0: 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70  inversion..** Ap
ba00: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
ba10: 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75  d <em>not</em> u
ba20: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
ba30: 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c  trol..**.** </ul
ba40: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
ba50: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
ba60: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
ba70: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
ba80: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
ba90: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
baa0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
bab0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
bac0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
bad0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
bae0: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
baf0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34  O              4
bb00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bb10: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
bb20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
bb30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bb40: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
bb50: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
bb60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bb70: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
bb80: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
bb90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bba0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
bbb0: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
bbc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bbd0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
bbe0: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
bbf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bc00: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
bc10: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
bc20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bc30: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
bc40: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
bc50: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
bc60: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
bc70: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
bc80: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
bc90: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
bca0: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
bcb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
bcc0: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
bcd0: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
bce0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
bcf0: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
bd00: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
bd10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
bd20: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
bd30: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
bd40: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
bd50: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bd60: 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   18.#define SQLI
bd70: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20  TE_FCNTL_TRACE  
bd80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bd90: 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  19.#define SQLIT
bda0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
bdb0: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  D              2
bdc0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
bdd0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20  _FCNTL_SYNC     
bde0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
bdf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
be00: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
be10: 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a  SETWO        22.
be20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
be30: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
be40: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23  ANDLE       23.#
be50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
be60: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20  NTL_WAL_BLOCK   
be70: 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 0a 2f             24../
be80: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
be90: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
bea0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
beb0: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
bec0: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
bed0: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
bee0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
bef0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
bf00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
bf10: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
bf20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
bf30: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
bf40: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
bf50: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
bf60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
bf70: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
bf80: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
bf90: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
bfa0: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
bfb0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
bfc0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
bfd0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
bfe0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
bff0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
c000: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
c010: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
c020: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
c030: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
c040: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
c050: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
c060: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c070: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
c080: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
c090: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
c0a0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
c0b0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
c0c0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c0d0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
c0e0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
c0f0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
c100: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
c110: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c120: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c130: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
c140: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
c150: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
c160: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
c170: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
c180: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
c190: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
c1a0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
c1b0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
c1c0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
c1d0: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
c1e0: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
c1f0: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
c200: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
c210: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
c220: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
c230: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
c240: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
c250: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
c260: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
c270: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
c280: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
c290: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
c2a0: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
c2b0: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
c2c0: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
c2d0: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
c2e0: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
c2f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
c300: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
c310: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
c320: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
c330: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
c340: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
c350: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
c360: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
c370: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
c380: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
c390: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
c3a0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
c3b0: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
c3c0: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
c3d0: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
c3e0: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
c3f0: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
c400: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
c410: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
c420: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
c430: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
c440: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
c450: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
c460: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
c470: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
c480: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
c490: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
c4a0: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
c4b0: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
c4c0: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
c4d0: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
c4e0: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
c4f0: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
c500: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
c510: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
c520: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
c530: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
c540: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
c550: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
c560: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
c570: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
c580: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
c590: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
c5a0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
c5b0: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
c5c0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
c5d0: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
c5e0: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
c5f0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
c600: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
c610: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
c620: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
c630: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
c640: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
c650: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
c660: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
c670: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
c680: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
c690: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
c6a0: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
c6b0: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
c6c0: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
c6d0: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
c6e0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
c6f0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
c700: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
c710: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
c720: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
c730: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
c740: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
c750: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
c760: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
c770: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c780: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
c790: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
c7a0: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
c7b0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
c7c0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
c7d0: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
c7e0: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
c7f0: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
c800: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
c810: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c820: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
c830: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
c840: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
c850: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
c860: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
c870: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
c880: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
c890: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
c8a0: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
c8b0: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
c8c0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
c8d0: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
c8e0: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
c8f0: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
c900: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
c910: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
c920: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
c930: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
c940: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
c950: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
c960: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
c970: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
c980: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
c990: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
c9a0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c9b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c9c0: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
c9d0: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
c9e0: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
c9f0: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
ca00: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
ca10: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
ca20: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
ca30: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
ca40: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
ca50: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
ca60: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
ca70: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
ca80: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
ca90: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
caa0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
cab0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
cac0: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
cad0: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
cae0: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
caf0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
cb00: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
cb10: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
cb20: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
cb30: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
cb40: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
cb50: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
cb60: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
cb70: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
cb80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
cb90: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
cba0: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
cbb0: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
cbc0: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
cbd0: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
cbe0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
cbf0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
cc00: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
cc10: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
cc20: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
cc30: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
cc40: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
cc50: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
cc60: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
cc70: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
cc80: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
cc90: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
cca0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ccb0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
ccc0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ccd0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
cce0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ccf0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
cd00: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
cd10: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
cd20: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
cd30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
cd40: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
cd50: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
cd60: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
cd70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cd80: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
cd90: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
cda0: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
cdb0: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
cdc0: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
cdd0: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
cde0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
cdf0: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
ce00: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
ce10: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
ce20: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
ce30: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
ce40: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
ce50: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
ce60: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
ce70: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
ce80: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
ce90: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
cea0: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
ceb0: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
cec0: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
ced0: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
cee0: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
cef0: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
cf00: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
cf10: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
cf20: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
cf30: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
cf40: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
cf50: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
cf60: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
cf70: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
cf80: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
cf90: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
cfa0: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
cfb0: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
cfc0: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
cfd0: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
cfe0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
cff0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d000: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d010: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d020: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
d030: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d040: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
d050: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
d060: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
d070: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
d080: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d090: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
d0a0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
d0b0: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
d0c0: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
d0d0: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
d0e0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d0f0: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
d100: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
d110: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
d120: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
d130: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
d140: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
d150: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
d160: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d170: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
d180: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
d190: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
d1a0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
d1b0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
d1c0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
d1d0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
d1e0: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
d1f0: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
d200: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
d210: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
d220: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
d230: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
d240: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
d250: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
d260: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
d270: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
d280: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
d290: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
d2a0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
d2b0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
d2c0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
d2d0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
d2e0: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
d2f0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
d300: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
d310: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
d320: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
d330: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
d340: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
d350: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
d360: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
d370: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
d380: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
d390: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
d3a0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
d3b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
d3c0: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
d3d0: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
d3e0: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
d3f0: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
d400: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
d410: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
d420: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
d430: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
d440: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
d450: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
d460: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
d470: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
d480: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
d490: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
d4a0: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
d4b0: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
d4c0: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
d4d0: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
d4e0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d4f0: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
d500: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
d510: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
d520: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
d530: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
d540: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
d550: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
d560: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
d570: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
d580: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
d590: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
d5a0: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
d5b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
d5c0: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
d5d0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
d5e0: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
d5f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d600: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
d610: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
d620: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
d630: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
d640: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d650: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
d660: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
d670: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
d680: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
d690: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
d6a0: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
d6b0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
d6c0: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
d6d0: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
d6e0: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
d6f0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
d700: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
d710: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
d720: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d730: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
d740: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
d750: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
d760: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
d770: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d780: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
d790: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
d7a0: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
d7b0: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
d7c0: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
d7d0: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
d7e0: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
d7f0: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
d800: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
d810: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
d820: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
d830: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
d840: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
d850: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
d860: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
d870: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
d880: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
d890: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d8a0: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
d8b0: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
d8c0: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
d8d0: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
d8e0: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
d8f0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
d900: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
d910: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
d920: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d930: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
d940: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
d950: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
d960: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
d970: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
d980: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
d990: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
d9a0: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
d9b0: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
d9c0: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
d9d0: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
d9e0: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
d9f0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
da00: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
da10: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
da20: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
da30: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
da40: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
da50: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
da60: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
da70: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
da80: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
da90: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
daa0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
dab0: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
dac0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
dad0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
dae0: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
daf0: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
db00: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
db10: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
db20: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
db30: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
db40: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
db50: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
db60: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
db70: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
db80: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
db90: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
dba0: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
dbb0: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
dbc0: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
dbd0: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
dbe0: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
dbf0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
dc00: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
dc10: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
dc20: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
dc30: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
dc40: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
dc50: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
dc60: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
dc70: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
dc80: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
dc90: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
dca0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
dcb0: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
dcc0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
dcd0: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
dce0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
dcf0: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
dd00: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
dd10: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
dd20: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
dd30: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
dd40: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
dd50: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
dd60: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
dd70: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
dd80: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
dd90: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
dda0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
ddb0: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
ddc0: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
ddd0: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
dde0: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
ddf0: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
de00: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
de10: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
de20: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
de30: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
de40: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
de50: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
de60: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
de70: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
de80: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
de90: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
dea0: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
deb0: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
dec0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
ded0: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
dee0: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
def0: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
df00: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
df10: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
df20: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
df30: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
df40: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
df50: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
df60: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
df70: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
df80: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
df90: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
dfa0: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
dfb0: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
dfc0: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
dfd0: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
dfe0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
dff0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
e000: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
e010: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
e020: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
e030: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
e040: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
e050: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
e060: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
e070: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
e080: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
e090: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
e0a0: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
e0b0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
e0c0: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
e0d0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
e0e0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
e0f0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
e100: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
e110: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
e120: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
e130: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
e140: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
e150: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
e160: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
e170: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
e180: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
e190: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e1a0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e1b0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
e1c0: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
e1d0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
e1e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
e1f0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e200: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e210: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
e220: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
e230: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
e240: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e250: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
e260: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
e270: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
e280: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
e290: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e2a0: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
e2b0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
e2c0: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
e2d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e2e0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
e2f0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
e300: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
e310: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
e320: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
e330: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
e340: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
e350: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
e360: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
e370: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
e380: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
e390: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
e3a0: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
e3b0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
e3c0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
e3d0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
e3e0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
e3f0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
e400: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
e410: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
e420: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
e430: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
e440: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
e450: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e460: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
e470: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e480: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e490: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
e4a0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e4b0: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
e4c0: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
e4d0: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
e4e0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
e4f0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
e500: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
e510: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
e520: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
e530: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
e540: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e550: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e560: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
e570: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e580: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
e590: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
e5a0: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
e5b0: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
e5c0: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
e5d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e5e0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e5f0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e600: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
e610: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
e620: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
e630: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e640: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
e650: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
e660: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
e670: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e680: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e690: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
e6a0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e6b0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e6c0: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
e6d0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e6e0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
e6f0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
e700: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
e710: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
e720: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
e730: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
e740: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
e750: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
e760: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e770: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
e780: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
e790: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
e7a0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
e7b0: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
e7c0: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
e7d0: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
e7e0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
e7f0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
e800: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
e810: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
e820: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
e830: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
e840: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
e850: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
e860: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
e870: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
e880: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
e890: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
e8a0: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
e8b0: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
e8c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
e8d0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
e8e0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
e8f0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
e900: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
e910: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
e920: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
e930: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
e940: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
e950: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
e960: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
e970: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
e980: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
e990: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e9a0: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
e9b0: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
e9c0: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
e9d0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
e9e0: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
e9f0: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
ea00: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
ea10: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
ea20: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
ea30: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
ea40: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
ea50: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
ea60: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
ea70: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
ea80: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
ea90: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
eaa0: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
eab0: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
eac0: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
ead0: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
eae0: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
eaf0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
eb00: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
eb10: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
eb20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
eb30: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
eb40: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
eb50: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
eb60: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
eb70: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
eb80: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
eb90: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
eba0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
ebb0: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
ebc0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
ebd0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
ebe0: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
ebf0: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
ec00: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
ec10: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
ec20: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
ec30: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
ec40: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
ec50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
ec60: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
ec70: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
ec80: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
ec90: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
eca0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
ecb0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
ecc0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ecd0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
ece0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
ecf0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
ed00: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
ed10: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
ed20: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
ed30: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
ed40: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
ed50: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
ed60: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
ed70: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
ed80: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
ed90: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
eda0: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
edb0: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
edc0: 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
edd0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
ede0: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
edf0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
ee00: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
ee10: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
ee20: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
ee30: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
ee40: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
ee50: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
ee60: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
ee70: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
ee80: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
ee90: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
eea0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
eeb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
eec0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
eed0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
eee0: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
eef0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
ef00: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
ef10: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
ef20: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
ef30: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
ef40: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
ef50: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
ef60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
ef70: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
ef80: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
ef90: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
efa0: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
efb0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
efc0: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
efd0: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
efe0: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
eff0: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
f000: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
f010: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
f020: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
f030: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
f040: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
f050: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
f060: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
f070: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f080: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f090: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
f0a0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
f0b0: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
f0c0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
f0d0: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
f0e0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
f0f0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
f100: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
f110: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
f120: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
f130: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
f140: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
f150: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f160: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
f170: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
f180: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
f190: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
f1a0: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
f1b0: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
f1c0: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
f1d0: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
f1e0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
f1f0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f200: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f210: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
f220: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
f230: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
f240: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f250: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
f260: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
f270: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
f280: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
f290: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
f2a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f2b0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f2c0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
f2d0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f2e0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
f2f0: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
f300: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
f310: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f320: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
f330: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
f340: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
f350: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
f360: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
f370: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f380: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
f390: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
f3a0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
f3b0: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
f3c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f3d0: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
f3e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f3f0: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
f400: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
f410: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f420: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
f430: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
f440: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
f450: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
f460: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f470: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
f480: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
f490: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
f4a0: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
f4b0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
f4c0: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
f4d0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
f4e0: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
f4f0: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
f500: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
f510: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
f520: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
f530: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
f540: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f550: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
f560: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
f570: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
f580: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
f590: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
f5a0: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
f5b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
f5c0: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
f5d0: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
f5e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f5f0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
f600: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f610: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
f620: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f630: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
f640: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f650: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
f660: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f670: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
f680: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
f690: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
f6a0: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
f6b0: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
f6c0: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
f6d0: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
f6e0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
f6f0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
f700: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
f710: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
f720: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
f730: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
f740: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
f750: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
f760: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
f770: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
f780: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
f790: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
f7a0: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
f7b0: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
f7c0: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
f7d0: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
f7e0: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
f7f0: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
f800: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
f810: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
f820: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
f830: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
f840: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
f850: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f860: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
f870: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
f880: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
f890: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
f8a0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f8b0: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
f8c0: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
f8d0: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
f8e0: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
f8f0: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
f900: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
f910: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
f920: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
f930: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
f940: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
f950: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
f960: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
f970: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
f980: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
f990: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
f9a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f9b0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
f9c0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
f9d0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
f9e0: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
f9f0: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
fa00: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
fa10: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
fa20: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
fa30: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
fa40: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
fa50: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
fa60: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
fa70: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fa80: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
fa90: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
faa0: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
fab0: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
fac0: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
fad0: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
fae0: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
faf0: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
fb00: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
fb10: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
fb20: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
fb30: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
fb40: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
fb50: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
fb60: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
fb70: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
fb80: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
fb90: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
fba0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
fbb0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
fbc0: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
fbd0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
fbe0: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
fbf0: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
fc00: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
fc10: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
fc20: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
fc30: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
fc40: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
fc50: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
fc60: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
fc70: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
fc80: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
fc90: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
fca0: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
fcb0: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
fcc0: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
fcd0: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
fce0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
fcf0: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
fd00: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
fd10: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
fd20: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
fd30: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
fd40: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
fd50: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
fd60: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
fd70: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
fd80: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
fd90: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
fda0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
fdb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fdc0: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
fdd0: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
fde0: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
fdf0: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
fe00: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
fe10: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
fe20: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
fe30: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
fe40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
fe50: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
fe60: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
fe70: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
fe80: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
fe90: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
fea0: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
feb0: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
fec0: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
fed0: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
fee0: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
fef0: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
ff00: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
ff10: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
ff20: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
ff30: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
ff40: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
ff50: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
ff60: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
ff70: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
ff80: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
ff90: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ffa0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
ffb0: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
ffc0: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
ffd0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
ffe0: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
fff0: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
10000 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
10010 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
10020 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
10030 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
10040 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
10050 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
10060 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
10070 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
10080 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10090 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
100a0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
100b0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
100c0 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
100d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
100e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
100f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
10100 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
10110 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
10120 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  LL sqlite3_os_en
10130 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
10140 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10150 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
10160 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
10170 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10180 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10190 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
101a0 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
101b0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
101c0 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
101d0 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
101e0 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
101f0 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
10200 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
10210 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
10220 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
10230 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
10240 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
10250 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
10260 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
10270 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
10280 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
10290 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
102a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
102b0 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
102c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
102d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
102e0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
102f0 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
10300 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
10310 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
10320 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
10330 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
10340 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
10350 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
10360 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10370 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
10380 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
10390 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
103a0 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
103b0 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
103c0 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
103d0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
103e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
103f0 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
10400 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
10410 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
10420 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
10430 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
10440 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
10450 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
10460 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
10470 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10480 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
10490 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
104a0 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
104b0 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
104c0 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
104d0 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
104e0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
104f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
10500 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10510 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
10520 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
10530 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10540 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
10550 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
10560 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
10570 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
10580 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
10590 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
105a0 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
105b0 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
105c0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
105d0 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
105e0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
105f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10600 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
10610 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
10620 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
10630 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10640 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
10650 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
10660 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
10670 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
10680 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
10690 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
106a0 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
106b0 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
106c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
106d0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
106e0 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49  r code]..*/.SQLI
106f0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
10700 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f  E_CDECL sqlite3_
10710 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
10720 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10730 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
10740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10750 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
10760 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
10770 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10780 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10790 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
107a0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
107b0 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
107c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
107d0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
107e0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
107f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10800 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
10810 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
10820 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
10830 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10840 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
10850 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
10860 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
10870 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
10880 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
10890 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
108a0 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
108b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
108c0 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
108d0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
108e0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
108f0 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
10900 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
10910 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
10920 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
10930 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
10940 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
10950 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
10960 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
10970 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10980 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
10990 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
109a0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
109b0 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
109c0 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
109d0 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
109e0 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
109f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10a00 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c  SQLITE_CDECL sql
10a10 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
10a20 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
10a30 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10a40 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
10a50 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
10a60 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
10a70 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10a80 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
10a90 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
10aa0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
10ab0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
10ac0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10ad0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
10ae0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
10af0 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
10b00 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
10b10 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
10b20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
10b30 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10b40 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
10b50 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
10b60 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10b70 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
10b80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
10b90 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
10ba0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
10bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10bc0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
10bd0 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
10be0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10bf0 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
10c00 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
10c10 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
10c20 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10c30 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
10c40 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
10c50 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
10c60 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
10c70 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
10c80 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
10c90 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
10ca0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
10cb0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
10cc0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
10cd0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
10ce0 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
10cf0 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
10d00 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10d10 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
10d20 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
10d30 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
10d40 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
10d50 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10d60 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
10d70 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
10d80 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
10d90 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
10da0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
10db0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
10dc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10dd0 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
10de0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
10df0 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
10e00 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
10e10 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
10e20 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
10e30 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10e40 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
10e50 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
10e60 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
10e70 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
10e80 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
10e90 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
10ea0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
10eb0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
10ec0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
10ed0 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
10ee0 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
10ef0 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
10f00 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
10f10 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
10f20 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
10f30 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
10f40 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
10f50 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
10f60 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
10f70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
10f80 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
10f90 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
10fa0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10fb0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
10fc0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
10fd0 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
10fe0 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
10ff0 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
11000 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
11010 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
11020 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
11030 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
11040 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
11050 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
11060 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
11070 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
11080 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
11090 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
110a0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
110b0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
110c0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
110d0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
110e0 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
110f0 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
11100 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
11110 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
11120 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
11130 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
11140 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11150 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
11160 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
11170 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
11180 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
11190 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
111a0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
111b0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
111c0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
111d0 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
111e0 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
111f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11200 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
11210 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
11220 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
11230 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
11240 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
11250 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
11260 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
11270 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11280 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
11290 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
112a0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
112b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
112c0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
112d0 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
112e0 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
112f0 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
11300 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
11310 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
11320 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
11330 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
11340 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
11350 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
11360 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
11370 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
11380 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
11390 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
113a0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
113b0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
113c0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
113d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
113e0 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
113f0 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
11400 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
11410 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
11420 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
11430 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
11440 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
11450 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
11460 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
11470 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
11480 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
11490 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
114a0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
114b0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
114c0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
114d0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
114e0 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
114f0 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
11500 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
11510 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
11520 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
11530 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
11540 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
11550 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11560 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
11570 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11580 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
11590 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
115a0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
115b0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
115c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
115d0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
115e0 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
115f0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11600 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
11610 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
11620 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
11630 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
11640 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
11650 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
11660 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
11670 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
11680 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
11690 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
116a0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
116b0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
116c0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
116d0 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
116e0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
116f0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11700 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
11710 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
11720 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11730 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
11740 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
11750 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
11760 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
11770 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
11780 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
11790 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
117a0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
117b0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
117c0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
117d0 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
117e0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
117f0 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
11800 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
11810 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
11820 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
11830 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11840 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
11850 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
11860 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
11870 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
11880 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
11890 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
118a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
118b0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
118c0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
118d0 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
118e0 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
118f0 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
11900 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11910 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11920 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
11930 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
11940 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
11950 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
11960 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
11970 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11980 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
11990 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
119a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
119b0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
119c0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
119d0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
119e0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
119f0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
11a00 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
11a10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11a20 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
11a30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11a40 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
11a50 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
11a60 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
11a70 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
11a80 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
11a90 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
11aa0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11ab0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
11ac0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
11ad0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
11ae0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
11af0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
11b00 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11b10 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
11b20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
11b30 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
11b40 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11b50 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
11b60 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
11b70 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
11b80 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
11b90 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
11ba0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
11bb0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
11bc0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
11bd0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
11be0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11bf0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11c00 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11c10 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11c20 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11c30 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11c40 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11c50 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11c60 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11c70 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
11c80 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
11c90 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11ca0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
11cb0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
11cc0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
11cd0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
11ce0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
11cf0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
11d00 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11d10 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11d20 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11d30 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11d40 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11d50 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11d60 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11d70 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
11d80 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
11d90 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
11da0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
11db0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
11dc0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
11dd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11de0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
11df0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
11e00 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
11e10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
11e20 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
11e30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11e40 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11e60 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
11e70 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11e80 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
11e90 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11ea0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
11eb0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
11ec0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11ed0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11ee0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
11ef0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
11f00 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11f10 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
11f20 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
11f30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11f40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11f50 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11f60 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
11f70 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
11f80 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
11f90 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
11fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11fb0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
11fc0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
11fd0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
11fe0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
11ff0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
12000 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
12010 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
12020 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
12030 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
12040 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
12050 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
12060 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
12070 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12080 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
12090 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
120a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
120b0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
120c0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
120d0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
120e0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
120f0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
12100 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
12110 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
12120 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
12130 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
12140 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12150 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12160 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12170 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12180 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12190 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
121a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
121b0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
121c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
121d0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
121e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
121f0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
12200 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12210 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
12220 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
12230 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
12240 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
12250 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
12260 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
12270 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
12280 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
12290 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
122a0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
122b0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
122c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
122d0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
122e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
122f0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
12300 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
12310 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
12320 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
12330 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
12340 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12350 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
12360 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
12370 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
12380 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
12390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
123a0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
123b0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
123c0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
123d0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
123e0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
123f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12400 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
12410 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
12420 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
12430 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
12440 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12450 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
12460 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12470 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
12480 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12490 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
124a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
124b0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
124c0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
124d0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
124e0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
124f0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
12500 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12510 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12520 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12530 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12540 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12550 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
12560 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12570 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12590 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
125a0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
125b0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
125c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
125d0 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
125e0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
125f0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
12600 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
12610 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12620 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12630 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12640 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
12650 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
12660 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
12670 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12680 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12690 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
126a0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
126b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
126c0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
126d0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
126e0 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
126f0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
12700 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
12710 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
12720 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12730 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
12740 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
12750 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
12760 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
12770 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12780 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
12790 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
127a0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
127b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
127c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
127d0 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
127e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
127f0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
12800 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
12810 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12820 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12830 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12840 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
12850 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12860 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
12870 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
12880 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
12890 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
128a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
128b0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
128c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
128d0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
128e0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
128f0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
12900 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
12910 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
12920 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
12930 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
12940 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
12950 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
12960 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
12970 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12980 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
12990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
129a0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
129b0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
129c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
129d0 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
129e0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
129f0 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
12a00 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
12a10 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
12a20 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
12a30 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
12a40 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
12a50 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12a60 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
12a70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12a80 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
12a90 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
12aa0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
12ab0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
12ac0 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
12ad0 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
12ae0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12af0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
12b00 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12b10 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
12b20 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
12b30 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
12b40 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
12b50 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12b60 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
12b70 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12b80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12b90 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12ba0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12bb0 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12bc0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12bd0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12be0 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
12bf0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
12c00 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
12c10 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
12c20 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
12c30 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
12c40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12c50 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
12c60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12c70 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
12c80 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12c90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12ca0 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
12cb0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12cc0 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
12cd0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
12ce0 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
12cf0 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
12d00 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12d10 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
12d20 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
12d30 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
12d40 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
12d50 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
12d60 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
12d70 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
12d80 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
12d90 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
12da0 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
12db0 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
12dc0 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
12dd0 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
12de0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
12df0 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
12e00 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
12e10 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12e20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12e30 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12e40 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12e50 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12e60 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
12e70 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
12e80 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
12e90 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
12ea0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12eb0 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
12ec0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
12ed0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
12ee0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
12ef0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
12f00 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
12f10 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
12f20 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12f30 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12f40 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12f50 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
12f60 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
12f70 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
12f80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
12f90 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
12fa0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
12fb0 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
12fc0 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
12fd0 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
12fe0 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
12ff0 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
13000 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
13010 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
13020 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
13030 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
13040 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
13050 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
13060 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
13070 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
13080 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
13090 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
130a0 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
130b0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
130c0 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
130d0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
130e0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
130f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13100 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
13110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13120 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
13130 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
13140 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
13150 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13160 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13170 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
13180 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
13190 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
131a0 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
131b0 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
131c0 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
131d0 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
131e0 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
131f0 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
13200 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
13210 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
13220 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
13230 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
13240 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
13250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13260 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67  ACHE2].** config
13270 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a  uration option..
13280 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
13290 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
132a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
132b0 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e  AGECACHE: A poin
132c0 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65  ter to.** 8-byte
132d0 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
132e0 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
132f0 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
13300 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
13310 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
13320 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
13330 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
13340 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
13350 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
13360 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
13370 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
13380 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
13390 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
133a0 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
133b0 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
133c0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
133d0 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
133e0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
133f0 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
13400 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
13410 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
13420 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
13430 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20  ] option .** to 
13440 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13450 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  )]..** ^It is ha
13460 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
13470 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
13480 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
13490 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
134a0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
134b0 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
134c0 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
134d0 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72  t should pointer
134e0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
134f0 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
13500 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69 73  emory that.** is
13510 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
13520 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
13530 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 65 71  otherwise subseq
13540 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
13550 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
13560 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
13570 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
13580 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
13590 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
135a0 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
135b0 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
135c0 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
135d0 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
135e0 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
135f0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
13600 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
13610 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
13620 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
13630 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
13640 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
13650 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
13660 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
13670 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
13680 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e  rage space.</dd>
13690 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
136a0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
136b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
136c0 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
136d0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
136e0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
136f0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13700 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13710 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
13720 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
13730 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
13740 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
13750 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
13760 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
13770 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
13780 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13790 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
137a0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
137b0 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
137c0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
137d0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
137e0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
137f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
13800 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
13810 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
13820 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
13830 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
13840 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
13850 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13860 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
13870 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
13880 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13890 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
138a0 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
138b0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
138c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
138d0 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
138e0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
138f0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
13900 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
13910 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
13920 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
13930 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
13940 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
13950 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
13960 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
13970 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
13980 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
13990 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
139a0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
139b0 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
139c0 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
139d0 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
139e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
139f0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
13a00 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
13a10 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
13a20 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
13a30 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
13a40 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
13a50 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
13a60 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
13a70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13a80 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
13a90 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
13aa0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
13ab0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
13ac0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
13ad0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
13ae0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
13af0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
13b00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
13b10 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13b20 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
13b30 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
13b40 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
13b50 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
13b60 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13b70 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
13b80 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
13b90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13ba0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
13bb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13bc0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13bd0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13be0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
13bf0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
13c00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
13c10 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
13c20 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
13c30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13c40 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13c50 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
13c60 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
13c70 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
13c80 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
13c90 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13ca0 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
13cb0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
13cc0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
13cd0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
13ce0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
13cf0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
13d00 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13d10 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13d20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
13d30 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
13d40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13d50 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
13d60 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13d70 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13d80 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13d90 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13da0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13db0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13dc0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13dd0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13de0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13df0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
13e00 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
13e10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13e20 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
13e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13e40 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
13e50 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13e60 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13e70 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13e80 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13e90 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
13ea0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13eb0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
13ec0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13ed0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13ee0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
13ef0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13f00 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
13f10 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13f20 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13f30 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13f40 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
13f50 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
13f60 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
13f70 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
13f80 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
13f90 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
13fa0 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
13fb0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13fc0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13fd0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13fe0 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
13ff0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
14000 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
14010 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
14020 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
14030 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
14040 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
14050 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
14060 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
14070 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14080 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14090 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
140a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
140b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
140c0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
140d0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
140e0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
140f0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
14100 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
14110 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
14120 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14130 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14140 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
14150 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14160 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14170 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14180 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
141a0 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
141b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
141c0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
141d0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
141e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
141f0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
14200 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
14210 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
14220 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
14230 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
14240 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
14250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14260 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
14270 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
14280 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
14290 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
142a0 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
142b0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
142c0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
142d0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
142e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
142f0 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
14300 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14310 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
14320 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
14330 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
14340 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
14350 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
14360 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
14370 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14380 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
14390 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
143a0 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
143b0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
143c0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
143d0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
143e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
143f0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14400 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14410 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14420 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14430 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
14440 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14450 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14460 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
14470 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14480 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14490 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
144a0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
144b0 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
144c0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
144d0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
144e0 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
144f0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14500 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
14510 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14520 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
14530 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14540 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14550 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14560 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
14570 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14580 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14590 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
145a0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
145b0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
145c0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
145d0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
145e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
145f0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
14600 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
14610 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
14620 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
14630 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
14640 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
14650 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14660 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
14670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
14680 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
14690 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
146a0 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
146b0 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
146c0 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
146d0 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
146e0 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
146f0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
14700 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
14710 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
14720 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
14730 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
14740 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
14750 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
14760 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
14770 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
14780 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
14790 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
147a0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
147b0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
147c0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
147d0 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
147e0 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
147f0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
14800 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
14810 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
14820 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
14830 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
14840 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
14850 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
14860 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
14870 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
14880 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
14890 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
148a0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
148b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
148c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
148d0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
148e0 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
148f0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
14900 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
14910 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
14920 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
14930 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
14940 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
14950 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14960 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
14970 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
14980 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
14990 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
149a0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
149b0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
149c0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
149d0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
149e0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
149f0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
14a00 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
14a10 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
14a20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
14a30 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
14a40 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
14a50 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
14a60 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
14a70 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
14a80 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
14a90 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
14aa0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
14ab0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
14ac0 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
14ad0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
14ae0 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
14af0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
14b00 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
14b10 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
14b20 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
14b30 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14b40 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
14b50 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
14b60 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
14b70 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
14b80 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14b90 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
14ba0 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
14bb0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
14bc0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
14bd0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
14be0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
14bf0 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
14c00 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14c10 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14c20 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
14c30 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14c40 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
14c50 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
14c60 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
14c70 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
14c80 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
14c90 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
14ca0 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
14cb0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
14cc0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
14cd0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
14ce0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
14cf0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
14d00 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
14d10 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
14d20 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
14d30 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
14d40 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
14d50 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
14d60 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14d70 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
14d80 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
14d90 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
14da0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
14db0 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
14dc0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
14dd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14de0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
14df0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
14e00 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14e10 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
14e20 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
14e30 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
14e40 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
14e50 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
14e60 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
14e70 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
14e80 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14e90 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14ea0 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
14eb0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14ec0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
14ed0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
14ee0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14ef0 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
14f00 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14f10 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
14f20 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
14f30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14f40 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
14f50 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14f60 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
14f70 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14f80 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
14f90 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
14fa0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
14fb0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
14fc0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
14fd0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
14fe0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14ff0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
15000 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
15010 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
15020 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
15030 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15040 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
15050 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
15060 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
15070 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
15080 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
15090 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
150a0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
150b0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
150c0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
150d0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
150e0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
150f0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
15100 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
15110 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
15120 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
15130 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15140 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
15150 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
15160 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
15170 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
15180 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
15190 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
151a0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
151b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
151c0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
151d0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
151e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
151f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
15200 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
15210 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
15220 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
15230 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
15240 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
15250 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
15260 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
15270 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
15280 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
15290 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
152a0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
152b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
152c0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
152d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
152e0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
152f0 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
15300 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15310 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
15320 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
15330 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
15340 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
15350 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
15360 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
15370 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
15380 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
15390 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
153a0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
153b0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
153c0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
153d0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
153e0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
153f0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
15400 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15410 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
15420 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
15430 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
15440 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
15450 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
15460 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
15470 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
15480 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15490 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
154a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
154b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
154c0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
154d0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
154e0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
154f0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
15500 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
15510 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
15520 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
15530 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
15540 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
15550 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15560 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
15570 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
15580 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
15590 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
155a0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
155b0 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
155c0 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
155d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
155e0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
155f0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
15600 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
15610 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
15620 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
15630 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
15640 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
15650 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
15660 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
15670 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
15680 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15690 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
156a0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
156b0 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
156c0 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
156d0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
156e0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
156f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15700 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
15710 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15720 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
15730 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
15740 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
15750 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
15760 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
15770 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
15780 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
15790 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
157a0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
157b0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
157c0 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
157d0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
157e0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
157f0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
15800 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
15810 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
15820 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
15830 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
15840 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
15850 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
15860 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
15870 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
15880 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
15890 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
158a0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
158b0 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
158c0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
158d0 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
158e0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
158f0 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
15900 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
15910 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
15920 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
15930 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
15940 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
15950 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
15960 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
15970 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
15980 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
15990 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
159a0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
159b0 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
159c0 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
159d0 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
159e0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
159f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15a00 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15a10 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15a20 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15a30 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
15a40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15a50 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
15a60 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
15a70 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
15a80 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
15a90 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
15aa0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
15ab0 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
15ac0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15ad0 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
15ae0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15af0 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
15b00 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
15b10 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
15b20 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
15b30 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
15b40 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
15b50 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
15b60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15b70 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
15b80 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15b90 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
15ba0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15bb0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15bc0 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
15bd0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
15be0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
15bf0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15c00 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
15c10 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
15c20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
15c30 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
15c40 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
15c50 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
15c60 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
15c70 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15c80 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
15c90 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
15ca0 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
15cb0 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
15cc0 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
15cd0 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
15ce0 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
15cf0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
15d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
15d10 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
15d20 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
15d30 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15d40 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
15d50 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15d60 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15d70 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
15d80 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
15d90 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
15da0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
15db0 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
15dc0 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
15dd0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
15de0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
15df0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
15e00 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
15e10 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
15e20 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
15e30 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
15e40 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
15e50 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
15e60 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
15e70 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
15e80 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
15e90 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
15ea0 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
15eb0 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
15ec0 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
15ed0 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
15ee0 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
15ef0 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
15f00 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
15f10 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
15f20 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
15f30 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
15f40 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f  his value..** </
15f50 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
15f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15f70 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
15f80 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
15f90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15fa0 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
15fb0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15fc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15fd0 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
15fe0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15ff0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16000 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
16010 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
16020 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16030 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16040 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
16050 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
16060 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16080 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
16090 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
160a0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
160b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
160c0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
160d0 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
160e0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
160f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16100 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
16110 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
16120 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
16130 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
16140 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16150 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
16160 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
16170 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16180 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
16190 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
161a0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
161b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
161c0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
161d0 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
161e0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
161f0 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
16200 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
16210 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
16220 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
16230 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
16240 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16250 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
16260 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
16270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16280 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
16290 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
162a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
162b0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
162c0 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
162d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
162e0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
162f0 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
16300 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
16310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16320 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
16330 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
16340 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16350 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
16360 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
16370 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
16380 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16390 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
163a0 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
163b0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
163c0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
163d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
163e0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
163f0 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
16400 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16410 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
16420 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
16430 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
16440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16450 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
16460 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
16470 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
16480 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65  int64 */.#define
16490 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
164a0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20  IN32_HEAPSIZE   
164b0 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42     23  /* int nB
164c0 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
164d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
164e0 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20  CHE_HDRSZ       
164f0 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a   24  /* int *psz
16500 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16510 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
16520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
16530 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e    /* unsigned in
16540 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a  t szPma */../*.*
16550 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
16560 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
16570 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
16580 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
16590 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
165a0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
165b0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
165c0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
165d0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
165e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
165f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
16600 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16610 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
16620 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
16630 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
16640 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
16650 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
16660 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
16670 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
16680 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
16690 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
166a0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
166b0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
166c0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
166d0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
166e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
166f0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
16700 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
16710 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
16720 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16730 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
16740 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
16750 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
16760 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
16770 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
16780 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
16790 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
167a0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
167b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
167c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
167d0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
167e0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
167f0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
16800 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
16810 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
16820 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
16830 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
16840 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16850 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
16860 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
16870 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
16880 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
16890 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
168a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
168b0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
168c0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
168d0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
168e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
168f0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
16900 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
16910 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
16920 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
16930 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
16940 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
16950 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
16960 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
16970 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
16980 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
16990 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
169a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
169b0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
169c0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
169d0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
169e0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
169f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
16a00 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
16a10 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
16a20 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
16a30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
16a40 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
16a50 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
16a60 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
16a70 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
16a80 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
16a90 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
16aa0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
16ab0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
16ac0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
16ad0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16ae0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
16af0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16b00 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
16b10 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
16b20 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
16b30 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
16b40 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
16b50 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
16b60 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
16b70 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
16b80 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
16b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16ba0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
16bb0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
16bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
16bd0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
16be0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
16bf0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
16c00 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
16c10 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
16c20 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
16c30 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
16c40 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
16c50 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16c60 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
16c70 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
16c80 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
16c90 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
16ca0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
16cb0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
16cc0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
16cd0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
16ce0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
16cf0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
16d00 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
16d10 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
16d20 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16d30 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
16d40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16d50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16d60 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
16d70 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
16d80 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
16d90 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
16da0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
16db0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
16dc0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
16dd0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16de0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
16df0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16e00 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
16e10 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
16e20 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16e30 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16e40 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16e50 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
16e60 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
16e70 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16e80 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16e90 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16ea0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
16eb0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
16ec0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
16ed0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
16ee0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
16ef0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
16f00 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16f10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16f20 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16f30 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16f40 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
16f50 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
16f60 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16f70 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
16f80 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16f90 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16fa0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
16fb0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
16fc0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
16fd0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
16fe0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
16ff0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
17000 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17010 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17020 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17030 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17040 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17050 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17060 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
17070 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17080 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
17090 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
170a0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
170b0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
170c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
170d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
170e0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
170f0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17100 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17110 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17120 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
17130 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
17140 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17150 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17160 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17170 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17180 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17190 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
171a0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
171b0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
171c0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
171d0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
171e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
171f0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
17200 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
17210 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
17220 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17230 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
17240 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
17250 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17260 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
17270 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
17280 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
17290 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
172a0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
172b0 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
172c0 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d  esult Codes.** M
172d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
172e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
172f0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
17300 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
17310 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
17320 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
17330 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
17340 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
17350 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
17360 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
17370 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
17380 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
17390 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
173a0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
173b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
173c0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
173d0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
173e0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
173f0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
17400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17410 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
17420 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
17430 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
17440 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
17450 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
17460 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
17470 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
17480 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
17490 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
174a0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
174b0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
174c0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
174d0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
174e0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
174f0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
17500 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
17510 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
17520 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
17530 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
17540 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
17550 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
17560 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
17570 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
17580 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
17590 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
175a0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
175b0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
175c0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
175d0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
175e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
175f0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17600 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
17610 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
17620 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
17630 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
17640 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17650 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
17660 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
17670 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
17680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17690 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
176a0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
176b0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
176c0 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
176d0 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
176e0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
176f0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
17700 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
17710 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
17720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17730 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
17740 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17750 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
17760 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
17770 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
17780 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
17790 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
177a0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
177b0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
177c0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
177d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
177e0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
177f0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
17800 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
17810 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17820 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
17830 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
17840 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
17850 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
17860 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
17870 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17880 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
17890 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
178a0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
178b0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
178c0 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
178d0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
178e0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
178f0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
17900 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17910 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17920 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
17930 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17940 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
17950 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
17960 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
17970 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
17980 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
17990 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
179a0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
179b0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
179c0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
179d0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
179e0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
179f0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
17a00 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17a10 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
17a20 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
17a30 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
17a40 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
17a50 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17a60 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
17a70 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
17a80 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
17a90 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
17aa0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
17ab0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
17ac0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
17ad0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
17ae0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
17af0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
17b00 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17b10 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17b20 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
17b30 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
17b40 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
17b50 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
17b60 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
17b70 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
17b80 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
17b90 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
17ba0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
17bb0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
17bc0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
17bd0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
17be0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
17bf0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
17c00 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17c10 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17c20 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
17c30 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
17c40 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17c50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17c60 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17c70 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17c80 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17c90 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17ca0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
17cb0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
17cc0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
17cd0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17ce0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
17cf0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17d00 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
17d10 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
17d20 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
17d30 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17d40 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17d50 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17d60 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
17d70 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
17d80 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
17d90 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
17da0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
17db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
17dc0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
17dd0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
17de0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
17df0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
17e00 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
17e10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
17e20 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e  ows modified, in
17e30 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  serted or.** del
17e40 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
17e50 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17e60 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
17e70 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  TE or DELETE.** 
17e80 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
17e90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17ea0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
17eb0 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  y the only param
17ec0 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74  eter..** ^Execut
17ed0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
17ee0 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
17ef0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ent does not mod
17f00 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ify the value.**
17f10 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
17f20 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
17f30 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  * ^Only changes 
17f40 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79  made directly by
17f50 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
17f60 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
17f70 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63  atement are.** c
17f80 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69  onsidered - auxi
17f90 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
17fa0 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20  used by [CREATE 
17fb0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17fc0 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67  rs], .** [foreig
17fd0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f  n key actions] o
17fe0 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  r [REPLACE] cons
17ff0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
18000 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  n are not counte
18010 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65  d..** .** Change
18020 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
18030 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
18040 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44   by .** [INSTEAD
18050 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e   OF trigger | IN
18060 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
18070 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
18080 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a  ed. ^The value .
18090 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
180a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
180b0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
180c0 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  er an INSERT, UP
180d0 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45  DATE or .** DELE
180e0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  TE statement run
180f0 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c   on a view is al
18100 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20  ways zero. Only 
18110 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20  changes made to 
18120 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20  real .** tables 
18130 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
18140 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f  ** Things are mo
18150 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69  re complicated i
18160 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  f the sqlite3_ch
18170 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
18180 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   is.** executed 
18190 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20  while a trigger 
181a0 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69  program is runni
181b0 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70  ng. This may hap
181c0 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  pen if the.** pr
181d0 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b  ogram uses the [
181e0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
181f0 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73  nction], or if s
18200 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61  ome other callba
18210 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ck.** function i
18220 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63  nvokes sqlite3_c
18230 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c  hanges() directl
18240 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a  y. Essentially:.
18250 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  ** .** <ul>.**  
18260 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65   <li> ^(Before e
18270 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65  ntering a trigge
18280 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61  r program the va
18290 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  lue returned by.
182a0 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65  **        sqlite
182b0 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
182c0 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41  tion is saved. A
182d0 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72  fter the trigger
182e0 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20   program .**    
182f0 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64      has finished
18300 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76  , the original v
18310 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64  alue is restored
18320 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69  .)^.** .**   <li
18330 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69  > ^(Within a tri
18340 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63  gger program eac
18350 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  h INSERT, UPDATE
18360 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20   and DELETE .** 
18370 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
18380 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20   sets the value 
18390 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
183a0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
183b0 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f  *        upon co
183c0 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d  mpletion as norm
183d0 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74  al. Of course, t
183e0 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e  his value will n
183f0 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20  ot include .**  
18400 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65        any change
18410 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73  s performed by s
18420 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20  ub-triggers, as 
18430 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
18440 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
18450 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73   value will be s
18460 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65  aved and restore
18470 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62  d after each sub
18480 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e  -trigger has run
18490 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  .)^.** </ul>.** 
184a0 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  .** ^This means 
184b0 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e  that if the chan
184c0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
184d0 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20  on (or similar) 
184e0 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  is used.** by th
184f0 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20  e first INSERT, 
18500 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
18510 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
18520 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20  n a trigger, it 
18530 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
18540 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65  value as set whe
18550 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74  n the calling st
18560 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78  atement began ex
18570 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20  ecuting..** ^If 
18580 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68  it is used by th
18590 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73  e second or subs
185a0 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74  equent such stat
185b0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
185c0 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72  rigger .** progr
185d0 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  am, the value re
185e0 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20  turned reflects 
185f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
18600 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ws modified by t
18610 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  he .** previous 
18620 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
18630 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
18640 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
18650 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  me trigger..**.*
18660 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
18670 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18680 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
18690 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
186a0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
186b0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
186c0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
186d0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
186e0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
186f0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
18700 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
18710 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18720 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
18730 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
18740 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
18750 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
18760 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
18770 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
18780 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
18790 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
187a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
187b0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
187c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
187d0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
187e0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
187f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18800 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
18810 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
18820 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
18830 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74  r of rows insert
18840 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a  ed, modified or.
18850 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c  ** deleted by al
18860 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  l [INSERT], [UPD
18870 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
18880 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70   statements comp
18890 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74  leted.** since t
188a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
188b0 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65  ection was opene
188c0 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f  d, including tho
188d0 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a  se executed as.*
188e0 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  * part of trigge
188f0 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65  r programs. ^Exe
18900 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
18910 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
18920 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e  tement.** does n
18930 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61  ot affect the va
18940 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
18950 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18960 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20  anges()..** .** 
18970 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73  ^Changes made as
18980 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67   part of [foreig
18990 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
189a0 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
189b0 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74  he.** count, but
189c0 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70   those made as p
189d0 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63  art of REPLACE c
189e0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
189f0 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e  tion are.** not.
18a00 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
18a10 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
18a20 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54  ercepted by INST
18a30 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20  EAD OF triggers 
18a40 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
18a50 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20  ted..** .** See 
18a60 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
18a70 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
18a80 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
18a90 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
18aa0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
18ab0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
18ac0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
18ad0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
18ae0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
18af0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
18b00 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
18b10 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
18b20 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
18b30 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
18b40 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
18b50 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
18b60 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
18b70 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
18b80 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
18b90 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
18ba0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74  TDCALL sqlite3_t
18bb0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
18bc0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18bd0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
18be0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
18bf0 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
18c00 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
18c10 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
18c20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
18c30 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
18c40 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
18c50 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
18c60 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
18c70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
18c80 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
18c90 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
18ca0 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
18cb0 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
18cc0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
18cd0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
18ce0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
18cf0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
18d00 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
18d10 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
18d20 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
18d30 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
18d40 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
18d50 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
18d60 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
18d70 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
18d80 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
18d90 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
18da0 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
18db0 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
18dc0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18dd0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
18de0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18df0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
18e00 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
18e10 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
18e20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
18e30 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
18e40 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
18e50 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
18e60 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
18e70 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
18e80 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18e90 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
18ea0 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
18eb0 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
18ec0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
18ed0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
18ee0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
18ef0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
18f00 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
18f10 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
18f20 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
18f30 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
18f40 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
18f50 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
18f60 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
18f70 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
18f80 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
18f90 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
18fa0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
18fb0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
18fc0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
18fd0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
18fe0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
18ff0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
19000 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
19010 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
19020 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
19030 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
19040 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
19050 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
19060 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19070 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
19080 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
19090 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
190a0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
190b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
190c0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
190d0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
190e0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
190f0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
19100 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
19110 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
19120 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
19130 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
19140 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19150 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
19160 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
19170 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
19180 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
19190 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
191a0 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
191b0 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
191c0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
191d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
191e0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
191f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
19200 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
19210 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
19220 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
19230 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
19240 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
19250 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
19260 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
19270 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
19280 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
19290 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
192a0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
192b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
192c0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
192d0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
192e0 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
192f0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
19300 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
19310 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
19320 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
19330 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
19340 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19350 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
19360 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
19370 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
19380 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
19390 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
193a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
193b0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
193c0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
193d0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
193e0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
193f0 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
19400 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
19410 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
19420 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
19430 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
19440 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
19450 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
19460 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
19470 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
19480 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
19490 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
194a0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
194b0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
194c0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
194d0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
194e0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
194f0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
19500 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
19510 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
19520 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
19530 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
19540 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
19550 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
19560 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
19570 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
19580 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
19590 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
195a0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
195b0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
195c0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
195d0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
195e0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
195f0 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
19600 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
19610 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
19620 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
19630 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
19640 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
19650 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
19660 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
19670 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
19680 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
19690 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
196a0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
196b0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
196c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
196d0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
196e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
196f0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
19700 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
19710 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
19720 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
19730 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
19740 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19750 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
19760 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
19770 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
19780 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
19790 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
197a0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
197b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
197c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
197d0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
197e0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
197f0 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
19800 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
19810 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
19820 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
19830 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
19840 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
19850 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
19860 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
19870 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
19880 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
19890 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
198a0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
198b0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
198c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
198d0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
198e0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
198f0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
19900 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
19910 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
19920 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
19930 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
19940 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
19950 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19960 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
19970 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
19980 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
19990 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
199a0 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  order..*/.SQLITE
199b0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
199c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
199d0 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
199e0 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54  har *sql);.SQLIT
199f0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
19a00 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
19a10 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
19a20 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
19a30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
19a40 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
19a50 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
19a60 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
19a70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75  ** KEYWORDS: {bu
19a80 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
19a90 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c  ack} {busy handl
19aa0 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
19ab0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19ac0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
19ad0 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
19ae0 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
19af0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
19b00 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
19b10 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
19b20 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
19b30 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
19b40 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
19b50 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
19b60 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
19b70 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
19b80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
19b90 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
19ba0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
19bb0 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
19bc0 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
19bd0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19be0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
19bf0 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
19c00 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
19c10 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
19c20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
19c30 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
19c40 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
19c50 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
19c60 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
19c70 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
19c80 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
19c90 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
19ca0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
19cb0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
19cc0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
19cd0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
19ce0 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
19cf0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
19d00 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
19d10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19d20 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
19d30 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
19d40 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
19d50 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
19d60 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
19d70 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
19d80 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
19d90 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
19da0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
19db0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
19dc0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
19dd0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
19de0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19df0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
19e00 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79  voked previously
19e10 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
19e20 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
19e30 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
19e40 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
19e50 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
19e60 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
19e70 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
19e80 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
19e90 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
19ea0 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
19eb0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
19ec0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
19ed0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19ee0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
19ef0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
19f00 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
19f10 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
19f20 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
19f30 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
19f40 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
19f50 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
19f60 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
19f70 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
19f80 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
19f90 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
19fa0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
19fb0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
19fc0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
19fd0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
19fe0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
19ff0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
1a000 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1a010 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1a020 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
1a030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1a040 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1a050 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
1a060 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
1a070 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
1a080 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
1a090 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1a0a0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
1a0b0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
1a0c0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
1a0d0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
1a0e0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
1a0f0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1a100 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1a110 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
1a120 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
1a130 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
1a140 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
1a150 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
1a160 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
1a170 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1a180 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
1a190 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
1a1a0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
1a1b0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
1a1c0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1a1d0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
1a1e0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
1a1f0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
1a200 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
1a210 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
1a220 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
1a230 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
1a240 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
1a250 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
1a260 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
1a270 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
1a280 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
1a290 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1a2a0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
1a2b0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
1a2c0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
1a2d0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
1a2e0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
1a2f0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
1a300 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
1a310 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1a320 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1a330 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1a340 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
1a350 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1a360 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
1a370 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
1a380 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
1a390 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
1a3a0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
1a3b0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
1a3c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1a3d0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
1a3e0 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
1a3f0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1a400 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
1a410 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
1a420 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
1a430 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
1a440 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
1a450 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1a460 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1a470 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1a480 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1a490 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1a4a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a4b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1a4c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1a4d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1a4e0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1a4f0 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
1a500 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
1a510 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1a520 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1a530 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1a540 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1a550 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1a560 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a570 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1a580 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1a590 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1a5a0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1a5b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1a5c0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
1a5d0 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  L sqlite3_busy_h
1a5e0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1a5f0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
1a600 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
1a610 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1a620 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1a630 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a640 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1a650 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1a660 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1a670 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1a680 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1a690 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1a6a0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1a6b0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1a6c0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1a6d0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1a6e0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1a6f0 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1a700 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1a710 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1a720 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1a730 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1a740 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1a750 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1a760 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1a770 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1a780 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1a790 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1a7a0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1a7b0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1a7c0 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1a7d0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1a7e0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1a7f0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1a800 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1a810 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1a820 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1a830 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1a840 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1a850 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1a860 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1a870 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1a880 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1a890 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1a8a0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1a8b0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1a8c0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1a8d0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1a8e0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1a8f0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1a900 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1a910 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1a920 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1a930 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
1a940 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c  _timeout].*/.SQL
1a950 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
1a960 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1a970 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1a980 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1a990 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a9a0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1a9b0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1a9c0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1a9d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a9e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1a9f0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1aa00 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1aa10 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1aa20 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1aa30 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1aa40 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1aa50 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1aa60 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1aa70 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1aa80 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1aa90 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1aaa0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1aab0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1aac0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1aad0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1aae0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1aaf0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1ab00 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1ab10 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1ab20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1ab30 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1ab40 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1ab50 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1ab60 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1ab70 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1ab80 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1ab90 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1aba0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1abb0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1abc0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1abd0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1abe0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1abf0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1ac00 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1ac10 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1ac20 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1ac30 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1ac40 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1ac50 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1ac60 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1ac70 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1ac80 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1ac90 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1aca0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1acb0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1acc0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1acd0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1ace0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1acf0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1ad00 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1ad10 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1ad20 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1ad30 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1ad40 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1ad50 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1ad60 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1ad70 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1ad80 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1ad90 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1ada0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1adb0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1adc0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1add0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1ade0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1adf0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1ae00 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1ae10 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1ae20 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1ae30 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1ae40 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1ae50 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1ae60 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1ae70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1ae80 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1ae90 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1aea0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1aeb0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1aec0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1aed0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1aee0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1aef0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1af00 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1af10 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1af20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1af30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1af40 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1af50 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1af60 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1af70 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1af80 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1af90 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1afa0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1afb0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1afc0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1afd0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1afe0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1aff0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1b000 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1b010 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1b020 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1b030 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1b040 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1b050 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1b060 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1b070 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b080 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1b090 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1b0a0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1b0b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b0c0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1b0d0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b0e0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1b0f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b100 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1b110 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1b120 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1b130 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1b140 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1b150 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1b160 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b170 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1b180 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b190 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1b1a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b1b0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1b1c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1b1d0 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1b1e0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1b1f0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1b200 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1b210 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1b220 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1b230 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1b240 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1b250 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1b260 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1b270 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1b280 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1b290 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1b2a0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1b2b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1b2c0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1b2d0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1b2e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b2f0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1b300 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1b310 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1b320 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1b330 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1b340 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1b350 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1b360 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1b370 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1b380 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1b390 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1b3a0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1b3b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1b3c0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1b3d0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1b3e0 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1b3f0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1b400 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1b410 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b420 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1b430 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1b440 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1b450 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1b460 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1b470 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1b480 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1b490 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1b4a0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1b4b0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1b4c0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b4d0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1b4e0 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1b4f0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1b500 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1b510 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1b520 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1b530 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1b540 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1b550 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1b560 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1b570 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1b580 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1b590 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1b5a0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1b5b0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1b5c0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1b5d0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1b5e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1b5f0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1b600 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1b610 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  g()]..*/.SQLITE_
1b620 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1b630 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67  TDCALL sqlite3_g
1b640 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1b650 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1b660 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1b670 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1b680 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1b690 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1b6a0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1b6b0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1b6c0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1b6d0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1b6e0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1b6f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1b700 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1b710 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1b720 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1b730 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1b740 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1b750 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1b760 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1b770 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1b780 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1b790 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
1b7a0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
1b7b0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1b7c0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1b7d0 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1b7e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1b7f0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1b800 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1b810 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1b820 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1b830 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1b840 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1b850 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1b860 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1b870 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
1b880 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75  These routines u
1b890 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f  nderstand most o
1b8a0 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52  f the common K&R
1b8b0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b8c0 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d  ons,.** plus som
1b8d0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e  e additional non
1b8e0 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74  -standard format
1b8f0 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f  s, detailed belo
1b900 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  w..** Note that 
1b910 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65  some of the more
1b920 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74   obscure formatt
1b930 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
1b940 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62   recent.** C-lib
1b950 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61  rary standards a
1b960 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  re omitted from 
1b970 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  this implementat
1b980 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
1b990 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b9a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1b9b0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1b9c0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1b9d0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1b9e0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1b9f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1ba00 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1ba10 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1ba20 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1ba30 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1ba40 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1ba50 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1ba60 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1ba70 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1ba80 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1ba90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1baa0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1bab0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1bac0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1bad0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1bae0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1baf0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1bb00 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1bb10 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1bb20 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1bb30 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1bb40 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1bb50 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1bb60 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1bb70 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1bb80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1bb90 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1bba0 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1bbb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1bbc0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1bbd0 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1bbe0 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1bbf0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1bc00 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1bc10 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1bc20 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1bc30 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1bc40 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1bc50 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1bc60 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1bc70 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1bc80 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1bc90 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1bca0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1bcb0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1bcc0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1bcd0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1bce0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1bcf0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1bd00 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1bd10 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1bd20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1bd30 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1bd40 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1bd50 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1bd60 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1bd70 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1bd80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1bd90 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1bda0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1bdb0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1bdc0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1bdd0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1bde0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1bdf0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1be00 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1be10 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1be20 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1be30 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1be40 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1be50 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1be60 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1be70 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1be80 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1be90 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1bea0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1beb0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1bec0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1bed0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1bee0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1bef0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1bf00 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1bf10 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1bf20 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1bf30 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1bf40 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1bf50 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1bf60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1bf70 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1bf80 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1bf90 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1bfa0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1bfb0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1bfc0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1bfd0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1bfe0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1bff0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1c000 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1c010 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1c020 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1c030 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22  "%Q", "%w" and "
1c040 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1c050 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1c060 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1c070 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1c080 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1c090 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1c0a0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1c0b0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1c0c0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1c0d0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1c0e0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1c0f0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1c100 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1c110 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1c120 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1c130 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1c140 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1c150 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1c160 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1c170 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1c180 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1c190 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1c1a0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1c1b0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1c1c0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1c1d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c1e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c1f0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1c200 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1c210 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1c220 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c230 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1c240 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1c250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1c260 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c270 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c280 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1c290 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1c2a0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1c2b0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1c2c0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1c2d0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1c2e0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1c2f0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1c300 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1c310 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1c320 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1c330 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1c340 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1c350 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1c360 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1c370 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1c380 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1c390 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1c3a0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c3b0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1c3c0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1c3d0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1c3e0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1c3f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c400 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1c410 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1c420 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1c430 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1c440 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1c450 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1c460 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1c470 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c480 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1c490 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1c4a0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1c4b0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1c4c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c4d0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1c4e0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1c4f0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1c500 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1c510 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1c520 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1c530 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1c540 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1c550 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1c560 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1c570 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1c580 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1c590 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1c5a0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1c5b0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1c5c0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1c5d0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1c5e0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1c5f0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1c600 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1c610 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1c620 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1c630 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1c640 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1c650 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1c660 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1c670 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1c680 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1c690 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1c6a0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1c6b0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1c6c0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1c6d0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1c6e0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1c6f0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1c700 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1c710 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1c720 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c730 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1c740 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1c750 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1c760 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1c770 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1c780 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1c790 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1c7a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1c7b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1c7c0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1c7d0 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71  tion is like "%q
1c7e0 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  " except that it
1c7f0 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62   expects to.** b
1c800 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68  e contained with
1c810 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73  in double-quotes
1c820 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67   instead of sing
1c830 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69  le quotes, and i
1c840 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65  t.** escapes the
1c850 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68   double-quote ch
1c860 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20  aracter instead 
1c870 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75  of the single-qu
1c880 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  ote.** character
1c890 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f  .)^  The "%w" fo
1c8a0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1c8b0 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
1c8c0 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67  safely inserting
1c8d0 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  .** table and co
1c8e0 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20  lumn names into 
1c8f0 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51  a constructed SQ
1c900 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
1c910 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
1c920 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1c930 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
1c940 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
1c950 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
1c960 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
1c970 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
1c980 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
1c990 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
1c9a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
1c9b0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
1c9c0 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
1c9d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1c9e0 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73   *SQLITE_CDECL s
1c9f0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1ca00 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1ca10 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1ca20 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1ca30 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1ca40 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1ca50 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f  a_list);.SQLITE_
1ca60 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1ca70 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 73  _CDECL sqlite3_s
1ca80 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1ca90 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1caa0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1cab0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
1cac0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e  CALL sqlite3_vsn
1cad0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1cae0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1caf0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1cb00 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1cb10 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1cb20 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1cb30 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1cb40 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1cb50 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1cb60 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1cb70 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1cb80 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1cb90 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1cba0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1cbb0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1cbc0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1cbd0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1cbe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1cbf0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1cc00 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1cc10 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1cc20 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1cc30 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1cc40 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1cc50 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1cc60 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1cc70 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1cc80 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1cc90 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1cca0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1ccb0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1ccc0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1ccd0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1cce0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1ccf0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1cd00 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1cd10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1cd20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1cd30 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1cd40 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1cd50 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1cd60 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1cd70 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1cd80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1cd90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cda0 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
1cdb0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
1cdc0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
1cdd0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
1cde0 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
1cdf0 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
1ce00 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1ce10 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
1ce20 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
1ce30 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1ce40 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1ce50 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1ce60 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1ce70 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1ce80 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1ce90 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1cea0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1ceb0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1cec0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1ced0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1cee0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1cef0 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1cf00 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1cf10 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1cf20 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1cf30 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1cf40 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1cf50 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1cf60 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1cf70 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1cf80 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1cf90 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1cfa0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1cfb0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1cfc0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1cfd0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1cfe0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1cff0 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1d000 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1d010 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1d020 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1d030 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1d040 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1d050 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1d060 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1d070 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1d080 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1d090 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1d0a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d0b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1d0c0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
1d0d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1d0e0 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
1d0f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1d100 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1d110 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d120 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
1d130 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
1d140 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
1d150 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1d160 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
1d170 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1d180 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1d190 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1d1a0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1d1b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
1d1c0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
1d1d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d1e0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1d1f0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1d200 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1d210 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1d220 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1d230 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1d240 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
1d250 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d260 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
1d270 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1d280 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1d290 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1d2a0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1d2b0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
1d2c0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
1d2d0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1d2e0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1d2f0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1d300 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1d310 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1d320 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1d330 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1d340 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1d350 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1d360 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1d370 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1d380 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1d390 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1d3a0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1d3b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d3c0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
1d3d0 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
1d3e0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
1d3f0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1d400 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1d410 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1d420 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
1d430 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
1d440 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
1d450 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d460 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1d470 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
1d480 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
1d490 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
1d4a0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1d4b0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
1d4c0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
1d4d0 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
1d4e0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
1d4f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d500 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1d510 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
1d520 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
1d530 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1d540 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
1d550 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1d560 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
1d570 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
1d580 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
1d590 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
1d5a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1d5b0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
1d5c0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
1d5d0 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
1d5e0 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
1d5f0 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
1d600 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
1d610 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1d620 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
1d630 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1d640 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
1d650 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
1d660 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
1d670 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
1d680 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
1d690 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
1d6a0 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
1d6b0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
1d6c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d6d0 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
1d6e0 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
1d6f0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
1d700 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d710 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
1d720 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
1d730 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
1d740 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1d750 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1d760 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
1d770 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1d780 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
1d790 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1d7a0 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
1d7b0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1d7c0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1d7d0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1d7e0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1d7f0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1d800 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1d810 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1d820 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1d830 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1d840 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1d850 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1d860 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1d870 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1d880 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1d890 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1d8a0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1d8b0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1d8c0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1d8d0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1d8e0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1d8f0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1d900 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1d910 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1d920 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1d930 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1d940 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1d950 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1d960 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1d970 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1d980 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1d990 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1d9a0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1d9b0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1d9c0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1d9d0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1d9e0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1d9f0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1da00 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1da10 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1da20 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1da30 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1da40 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1da50 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1da60 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1da70 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1da80 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1da90 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1daa0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1dab0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1dac0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1dad0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1dae0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1daf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1db00 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1db10 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1db20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1db30 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1db40 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1db50 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1db60 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1db70 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1db80 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1db90 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1dba0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1dbb0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1dbc0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1dbd0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1dbe0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1dbf0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1dc00 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1dc10 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1dc20 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1dc30 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1dc40 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1dc50 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1dc60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1dc70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1dc80 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
1dc90 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ALL sqlite3_mall
1dca0 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  oc(int);.SQLITE_
1dcb0 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  API void *SQLITE
1dcc0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1dcd0 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1dce0 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
1dcf0 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
1dd00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1dd10 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1dd20 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
1dd30 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
1dd40 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1dd50 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1dd60 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1dd70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1dd80 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
1dd90 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1dda0 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  id*);.SQLITE_API
1ddb0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
1ddc0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1ddd0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69  qlite3_msize(voi
1dde0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1ddf0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1de00 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
1de10 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
1de20 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
1de30 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
1de40 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
1de50 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
1de60 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
1de70 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
1de80 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
1de90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1dea0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
1deb0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
1dec0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1ded0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
1dee0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
1def0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1df00 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
1df10 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1df20 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
1df30 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
1df40 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
1df50 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
1df60 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
1df70 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1df80 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
1df90 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1dfa0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
1dfb0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
1dfc0 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
1dfd0 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
1dfe0 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
1dff0 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
1e000 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1e010 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1e020 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
1e030 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e040 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
1e050 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
1e060 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
1e070 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
1e080 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1e090 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e0a0 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
1e0b0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
1e0c0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
1e0d0 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
1e0e0 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
1e0f0 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
1e100 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
1e110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1e120 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
1e130 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
1e140 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1e150 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
1e160 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
1e170 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
1e180 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1e190 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e1a0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
1e1b0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
1e1c0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
1e1d0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1e1e0 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
1e1f0 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
1e200 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
1e210 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
1e220 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
1e230 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
1e240 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1e250 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1e260 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
1e270 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
1e280 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1e290 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1e2a0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1e2b0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1e2c0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1e2d0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1e2e0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1e2f0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1e300 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1e310 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1e320 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1e330 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1e340 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1e350 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1e360 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1e370 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1e380 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1e390 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1e3a0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1e3b0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1e3c0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1e3d0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1e3e0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1e3f0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1e400 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1e410 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1e420 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1e430 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1e440 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1e450 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1e460 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1e470 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1e480 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1e490 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1e4a0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
1e4b0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
1e4c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e4d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
1e4e0 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
1e4f0 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
1e500 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
1e510 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
1e520 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
1e530 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
1e540 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
1e550 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
1e560 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
1e570 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1e580 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1e590 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1e5a0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
1e5b0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1e5c0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
1e5d0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
1e5e0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
1e5f0 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
1e600 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
1e610 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
1e620 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1e630 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1e640 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1e650 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1e660 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1e670 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1e680 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1e690 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1e6a0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
1e6b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  ALL sqlite3_rand
1e6c0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
1e6d0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
1e6e0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
1e6f0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
1e700 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1e710 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1e720 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1e730 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1e740 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1e750 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1e760 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1e770 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1e780 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1e790 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1e7a0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1e7b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e7c0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1e7d0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1e7e0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
1e7f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
1e800 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1e810 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
1e820 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
1e830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e840 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
1e850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e860 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
1e870 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
1e880 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
1e890 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
1e8a0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
1e8b0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
1e8c0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
1e8d0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
1e8e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1e8f0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
1e900 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
1e910 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
1e920 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
1e930 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
1e940 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
1e950 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
1e960 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
1e970 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
1e980 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
1e990 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
1e9a0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
1e9b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1e9c0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
1e9d0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
1e9e0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
1e9f0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
1ea00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1ea10 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
1ea20 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
1ea30 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1ea40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
1ea50 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
1ea60 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1ea70 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
1ea80 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
1ea90 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
1eaa0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1eab0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1eac0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1ead0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1eae0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1eaf0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1eb00 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1eb10 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
1eb20 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1eb30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
1eb40 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1eb50 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
1eb60 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
1eb70 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1eb80 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1eb90 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
1eba0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ebb0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1ebc0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1ebd0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
1ebe0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1ebf0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1ec00 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
1ec10 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
1ec20 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
1ec30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1ec40 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
1ec50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ec60 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1ec70 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
1ec80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ec90 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1eca0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
1ecb0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
1ecc0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
1ecd0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1ece0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
1ecf0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
1ed00 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
1ed10 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
1ed20 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1ed30 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1ed40 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
1ed50 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
1ed60 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
1ed70 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
1ed80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1ed90 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
1eda0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
1edb0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1edc0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1edd0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1ede0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1edf0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1ee00 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
1ee10 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1ee20 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
1ee30 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
1ee40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ee50 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
1ee60 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
1ee70 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
1ee80 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
1ee90 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1eea0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1eeb0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
1eec0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
1eed0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
1eee0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
1eef0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
1ef00 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
1ef10 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
1ef20 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
1ef30 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
1ef40 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
1ef50 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
1ef60 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1ef70 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
1ef80 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
1ef90 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
1efa0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1efb0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
1efc0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1efd0 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
1efe0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
1eff0 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
1f000 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
1f010 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
1f020 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
1f030 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
1f040 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
1f050 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1f060 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
1f070 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
1f080 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
1f090 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
1f0a0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
1f0b0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
1f0c0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
1f0d0 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
1f0e0 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
1f0f0 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
1f100 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
1f110 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
1f120 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
1f130 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
1f140 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
1f150 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
1f160 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
1f170 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
1f180 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
1f190 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
1f1a0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
1f1b0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
1f1c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
1f1d0 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
1f1e0 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
1f1f0 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
1f200 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
1f210 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
1f220 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
1f230 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
1f240 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
1f250 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
1f260 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
1f270 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1f280 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
1f290 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
1f2a0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
1f2b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1f2c0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
1f2d0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
1f2e0 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
1f2f0 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
1f300 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
1f310 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
1f320 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
1f330 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
1f340 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1f350 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
1f360 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
1f370 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
1f380 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1f390 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
1f3a0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
1f3b0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
1f3c0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
1f3d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
1f3e0 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
1f3f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f400 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
1f410 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
1f420 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f430 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
1f440 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
1f450 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
1f460 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
1f470 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
1f480 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
1f490 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1f4a0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
1f4b0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
1f4c0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1f4d0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1f4e0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1f4f0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1f500 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1f510 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1f520 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
1f530 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
1f540 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1f550 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f560 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1f570 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1f580 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1f590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f5a0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1f5b0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1f5c0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1f5d0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
1f5e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f5f0 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
1f600 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1f610 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
1f620 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
1f630 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
1f640 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f650 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
1f660 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
1f670 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
1f680 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
1f690 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1f6a0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
1f6b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
1f6c0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
1f6d0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1f6e0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1f6f0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
1f700 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f710 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1f720 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
1f730 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1f740 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1f750 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
1f760 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
1f770 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
1f780 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
1f790 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
1f7a0 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
1f7b0 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
1f7c0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
1f7d0 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
1f7e0 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
1f7f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f800 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
1f810 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
1f820 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
1f830 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ge..*/.SQLITE_AP
1f840 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1f850 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74  CALL sqlite3_set
1f860 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1f870 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1f880 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1f890 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1f8a0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1f8b0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1f8c0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1f8d0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1f8e0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1f8f0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1f900 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1f910 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f920 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1f930 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f940 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1f950 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1f960 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1f970 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1f980 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1f990 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1f9a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1f9b0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1f9c0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1f9d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1f9e0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1f9f0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1fa00 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1fa10 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1fa20 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1fa30 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1fa40 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1fa50 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
1fa60 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
1fa70 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
1fa80 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1fa90 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1faa0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1fab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fac0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1fad0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1fae0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1faf0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1fb00 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1fb10 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1fb20 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1fb30 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1fb40 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1fb50 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1fb60 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1fb70 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1fb80 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1fb90 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1fba0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1fbb0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1fbc0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1fbd0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1fbe0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1fbf0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1fc00 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1fc10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1fc20 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1fc30 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1fc40 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1fc50 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1fc60 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1fc70 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1fc80 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1fc90 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1fca0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1fcb0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1fcc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1fcd0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1fce0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1fcf0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1fd00 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1fd10 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1fd20 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1fd30 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1fd40 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1fd50 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1fd60 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1fd70 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1fd80 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1fd90 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1fda0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1fdb0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1fdc0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1fdd0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1fde0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1fdf0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1fe00 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1fe10 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1fe20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1fe30 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1fe40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1fe50 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1fe60 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1fe70 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1fe80 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1fe90 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1fea0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1feb0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1fec0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1fed0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1fee0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1fef0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1ff00 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1ff10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ff20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ff30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1ff40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1ff50 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1ff60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ff70 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1ff80 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1ff90 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1ffa0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ffb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ffc0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1ffd0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1ffe0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1fff0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20000 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
20010 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
20020 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
20030 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
20040 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
20050 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20060 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
20070 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
20080 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20090 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
200a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
200b0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
200c0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
200d0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
200e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
200f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
20100 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
20110 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
20120 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20130 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20140 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
20150 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
20160 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
20170 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20180 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20190 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
201a0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
201b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
201c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
201d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
201e0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
201f0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
20200 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20210 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20220 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20230 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
20240 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
20250 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20260 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20280 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
20290 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
202a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
202b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
202c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
202d0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
202e0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
202f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
20300 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20310 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20320 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
20330 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
20340 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20350 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20370 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
20380 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
20390 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
203a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
203b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
203c0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
203d0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
203e0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
203f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20400 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
20410 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
20420 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
20430 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
20440 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20460 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
20470 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
20480 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
20490 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
204a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
204b0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
204c0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
204d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
204e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
204f0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
20500 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
20510 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
20520 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
20530 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
20540 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
20550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20560 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
20570 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
20580 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20590 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
205a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
205b0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
205c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
205d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
205e0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
205f0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
20600 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
20610 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20620 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20630 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
20640 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
20650 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20660 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
20670 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20680 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
20690 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
206a0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
206b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
206c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
206d0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
206e0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
206f0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
20700 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20710 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20720 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
20730 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
20740 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
20750 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20770 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
20780 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
20790 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
207a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
207b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
207c0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
207d0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
207e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
207f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20800 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20810 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
20820 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
20830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
20840 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
20850 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20860 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
20870 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
20880 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
20890 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
208a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
208b0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
208c0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
208d0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
208e0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
208f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
20900 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
20910 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
20920 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
20930 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
20940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
20950 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
20960 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
20970 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
20980 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
20990 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
209a0 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
209b0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
209c0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
209d0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
209e0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
209f0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
20a00 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
20a10 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20a20 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
20a30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
20a40 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
20a50 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
20a60 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
20a70 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
20a80 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
20a90 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
20aa0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
20ab0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
20ac0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
20ad0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
20ae0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
20af0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
20b00 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
20b10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
20b20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20b30 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
20b40 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
20b50 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
20b60 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
20b70 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
20b80 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
20b90 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
20ba0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
20bb0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
20bc0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
20bd0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
20be0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
20bf0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
20c00 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
20c10 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
20c20 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
20c30 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
20c40 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
20c50 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
20c60 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
20c70 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
20c80 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
20c90 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
20ca0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
20cb0 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
20cc0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
20cd0 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
20ce0 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
20cf0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20d00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
20d10 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
20d20 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
20d30 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
20d40 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
20d50 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
20d60 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
20d70 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20d80 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
20d90 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
20da0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
20db0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
20dc0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
20dd0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
20de0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
20df0 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
20e00 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
20e10 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
20e20 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
20e30 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
20e40 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
20e50 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
20e60 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
20e70 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
20e80 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
20e90 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
20ea0 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
20eb0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
20ec0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
20ed0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
20ee0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
20ef0 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
20f00 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
20f10 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
20f20 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
20f30 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
20f40 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
20f50 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
20f60 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
20f70 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
20f80 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20f90 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
20fa0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
20fb0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
20fc0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
20fd0 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
20fe0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
20ff0 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
21000 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
21010 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
21020 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
21030 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  LL sqlite3_profi
21040 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
21050 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
21060 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
21070 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
21080 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
21090 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
210a0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
210b0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
210c0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
210d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
210e0 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
210f0 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
21100 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
21110 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
21120 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
21130 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
21140 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
21150 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
21160 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
21170 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
21180 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
21190 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
211a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
211b0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
211c0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
211d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
211e0 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
211f0 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
21200 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
21210 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
21220 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
21230 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
21240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21250 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
21260 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
21270 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
21280 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
21290 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
212a0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
212b0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
212c0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
212d0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
212e0 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
212f0 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
21300 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
21310 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
21320 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
21330 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
21340 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
21350 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
21360 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
21370 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
21380 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
21390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
213a0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
213b0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
213c0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
213d0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
213e0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
213f0 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
21400 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
21410 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
21420 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
21430 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
21440 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
21450 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
21460 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
21470 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
21480 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
21490 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
214a0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
214b0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
214c0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
214d0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
214e0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
214f0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
21500 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
21510 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
21520 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
21530 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
21540 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
21550 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
21560 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
21570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
21580 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
21590 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
215a0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
215b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
215c0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
215d0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
215e0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
215f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21600 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
21610 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
21620 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
21630 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f  h..**.*/.SQLITE_
21640 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
21650 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
21660 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
21670 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
21680 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
21690 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
216a0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
216b0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
216c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e  onnection.** CON
216d0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
216e0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  3.**.** ^These r
216f0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
21700 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
21710 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
21720 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
21730 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
21740 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
21750 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
21760 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
21770 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
21780 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
21790 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
217a0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
217b0 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
217c0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
217d0 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
217e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
217f0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
21800 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
21810 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
21820 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
21830 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
21840 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
21850 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
21860 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
21870 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
21880 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
21890 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
218a0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
218b0 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
218c0 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
218d0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
218e0 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
218f0 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
21900 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
21910 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
21920 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
21930 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
21940 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
21950 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
21960 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
21970 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
21980 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
21990 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
219a0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
219b0 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
219c0 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
219d0 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
219e0 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
219f0 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
21a00 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
21a10 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
21a20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
21a30 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
21a40 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
21a50 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ing will be UTF-
21a60 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20  8 for databases 
21a70 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
21a80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21a90 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
21aa0 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61  v2().  ^The defa
21ab0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
21ac0 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72   databases.** cr
21ad0 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  eated using sqli
21ae0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c  te3_open16() wil
21af0 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74  l be UTF-16 in t
21b00 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
21b10 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  rder..**.** Whet
21b20 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
21b30 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
21b40 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
21b50 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
21b60 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
21b70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21b80 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
21b90 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
21ba0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
21bb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
21bc0 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
21bd0 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
21be0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
21bf0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
21c00 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
21c10 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
21c20 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
21c30 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
21c40 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
21c50 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
21c60 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
21c70 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
21c80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21c90 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
21ca0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
21cb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21cc0 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
21cd0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
21ce0 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
21cf0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
21d00 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
21d10 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21d20 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
21d30 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
21d40 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
21d50 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
21d60 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
21d70 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
21d80 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
21d90 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
21da0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
21db0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
21dc0 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
21dd0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
21de0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
21df0 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
21e00 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
21e10 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
21e20 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
21e30 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
21e40 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
21e50 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
21e60 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
21e70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
21e80 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21e90 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
21ea0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
21eb0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
21ec0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
21ed0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
21ee0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
21ef0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
21f00 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
21f10 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
21f20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
21f30 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
21f40 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
21f50 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
21f60 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
21f70 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
21f80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
21f90 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
21fa0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
21fb0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
21fc0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
21fd0 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
21fe0 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
21ff0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
22000 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
22010 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
22020 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
22030 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
22040 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
22050 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
22060 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
22070 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
22080 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
22090 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
220a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
220b0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
220c0 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
220d0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
220e0 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
220f0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
22100 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
22110 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
22120 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
22130 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
22140 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
22150 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
22160 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
22170 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22180 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
22190 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
221a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
221b0 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
221c0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
221d0 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
221e0 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
221f0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
22200 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
22210 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
22220 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
22230 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
22240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22250 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
22260 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
22270 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
22280 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
22290 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
222a0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
222b0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
222c0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
222d0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
222e0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
222f0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
22300 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22310 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
22320 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
22330 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
22340 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
22350 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
22360 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
22370 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
22380 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
22390 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
223a0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
223b0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
223c0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
223d0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
223e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
223f0 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
22400 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
22410 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
22420 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
22430 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
22440 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
22450 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
22460 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22470 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
22480 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
22490 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
224a0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
224b0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
224c0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
224d0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
224e0 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
224f0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
22500 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
22510 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
22520 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
22530 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
22540 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
22550 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
22560 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
22570 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
22580 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
22590 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
225a0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
225b0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
225c0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
225d0 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
225e0 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
225f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
22600 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
22610 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
22620 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
22630 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
22640 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
22650 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
22660 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
22670 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
22680 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
22690 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
226a0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
226b0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
226c0 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
226d0 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
226e0 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
226f0 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
22700 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
22710 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
22720 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
22730 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
22740 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
22750 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
22760 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
22770 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
22780 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
22790 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
227a0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
227b0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
227c0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
227d0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
227e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
227f0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
22800 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
22810 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
22820 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
22830 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
22840 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
22850 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
22860 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
22870 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
22880 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
22890 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
228a0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
228b0 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
228c0 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
228d0 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
228e0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
228f0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
22900 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
22910 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
22920 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
22930 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
22940 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
22950 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
22960 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
22970 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
22980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
22990 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
229a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
229b0 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
229c0 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
229d0 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
229e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
229f0 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
22a00 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
22a10 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
22a20 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
22a30 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
22a40 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
22a50 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
22a60 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
22a70 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
22a80 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
22a90 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
22aa0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
22ab0 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
22ac0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
22ad0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
22ae0 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
22af0 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
22b00 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
22b10 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
22b20 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
22b30 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
22b40 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
22b50 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
22b60 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
22b70 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
22b80 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
22b90 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
22ba0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
22bb0 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
22bc0 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
22bd0 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
22be0 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
22bf0 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
22c00 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
22c10 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
22c20 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
22c30 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
22c40 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
22c50 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
22c60 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
22c70 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
22c80 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
22c90 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
22ca0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
22cb0 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
22cc0 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
22cd0 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
22ce0 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
22cf0 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
22d00 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
22d10 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
22d20 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
22d30 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
22d40 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
22d50 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
22d60 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
22d70 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f  ve path. .** ^(O
22d80 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
22d90 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
22da0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
22db0 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
22dc0 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
22dd0 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a  (e.g. "C:").)^.*
22de0 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
22df0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
22e00 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
22e10 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
22e20 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
22e30 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
22e40 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
22e50 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
22e60 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
22e70 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
22e80 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
22e90 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
22ea0 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e  and its built-in
22eb0 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72   [VFSes] interpr
22ec0 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  et the.** follow
22ed0 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65  ing query parame
22ee0 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
22ef0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
22f00 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
22f10 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
22f20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
22f30 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
22f40 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
22f50 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
22f60 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
22f70 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
22f80 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
22f90 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
22fa0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
22fb0 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
22fc0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
22fd0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
22fe0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22ff0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
23000 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
23010 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
23020 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
23030 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
23040 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
23050 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
23060 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
23070 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
23080 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
23090 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
230a0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
230b0 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
230c0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
230d0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
230e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
230f0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
23100 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
23110 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
23120 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
23130 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
23140 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
23150 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
23160 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
23170 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
23180 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
23190 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
231a0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
231b0 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
231c0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
231d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
231e0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
231f0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
23200 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
23210 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
23220 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
23230 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
23240 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
23250 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
23260 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23270 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
23280 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
23290 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
232a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
232b0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
232c0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
232d0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
232e0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
232f0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
23300 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
23310 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
23320 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
23330 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
23340 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
23350 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
23360 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
23370 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
23380 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
23390 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
233a0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
233b0 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
233c0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
233d0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
233e0 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
233f0 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
23400 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
23410 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
23420 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
23430 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
23440 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
23450 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
23460 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
23470 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
23480 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
23490 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
234a0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
234b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
234c0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
234d0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
234e0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
234f0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
23500 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
23510 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
23520 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
23530 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
23540 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
23550 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
23560 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
23570 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
23580 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
23590 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
235a0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
235b0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
235c0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
235d0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
235e0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
235f0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
23600 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
23610 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
23620 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
23630 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
23640 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
23650 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
23660 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
23670 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
23680 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
23690 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
236a0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
236b0 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
236c0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
236d0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
236e0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
236f0 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
23700 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
23710 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  g..**.**  <li> <
23720 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65  b>psow</b>: ^The
23730 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20   psow parameter 
23740 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65  indicates whethe
23750 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20  r or not the.** 
23760 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
23770 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
23780 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
23790 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
237a0 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
237b0 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
237c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
237d0 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20   resides..**.** 
237e0 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
237f0 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
23800 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
23810 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
23820 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
23830 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
23840 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
23850 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
23860 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
23870 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
23880 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
23890 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
238a0 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
238b0 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
238c0 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
238d0 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
238e0 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
238f0 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
23900 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
23910 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
23920 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
23930 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
23940 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
23950 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
23960 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
23970 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
23980 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
23990 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
239a0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
239b0 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
239c0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
239d0 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
239e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
239f0 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
23a00 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
23a10 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
23a20 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
23a30 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
23a40 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
23a50 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
23a60 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
23a70 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
23a80 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
23a90 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
23aa0 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
23ab0 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
23ac0 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
23ad0 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
23ae0 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
23af0 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
23b00 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
23b10 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
23b20 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
23b30 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
23b40 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
23b50 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
23b60 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
23b70 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
23b80 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
23b90 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
23ba0 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
23bb0 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
23bc0 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
23bd0 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
23be0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
23bf0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
23c00 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
23c10 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
23c20 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
23c30 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
23c40 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
23c50 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
23c60 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
23c70 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
23c80 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
23c90 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
23ca0 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
23cb0 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
23cc0 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
23cd0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
23ce0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
23cf0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
23d00 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
23d10 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
23d20 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
23d30 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
23d40 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
23d50 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
23d60 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
23d70 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
23d80 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23d90 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
23da0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
23db0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
23dc0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
23dd0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
23de0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
23df0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
23e00 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
23e10 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
23e20 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
23e30 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
23e40 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
23e50 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
23e60 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
23e70 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
23e80 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
23e90 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23ea0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
23eb0 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
23ec0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23ed0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23ee0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
23ef0 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
23f00 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
23f10 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
23f20 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
23f30 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
23f40 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
23f50 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
23f60 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
23f70 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
23f80 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
23f90 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
23fa0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
23fb0 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
23fc0 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
23fd0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
23fe0 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
23ff0 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
24000 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
24010 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
24020 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
24030 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
24040 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
24050 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
24060 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
24070 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
24080 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
24090 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
240a0 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
240b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
240c0 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
240d0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
240e0 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
240f0 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
24100 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
24110 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
24120 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
24130 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
24140 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
24150 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
24160 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
24170 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
24180 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
24190 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
241a0 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
241b0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
241c0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
241d0 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
241e0 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
241f0 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
24200 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
24210 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
24220 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
24230 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
24240 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
24250 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
24260 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
24270 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
24280 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
24290 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
242a0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
242b0 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
242c0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
242d0 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
242e0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
242f0 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
24300 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
24310 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
24320 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
24330 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
24340 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
24350 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
24360 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
24370 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
24380 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
24390 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
243a0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
243b0 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
243c0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
243d0 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
243e0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
243f0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
24400 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
24410 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
24420 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
24430 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
24440 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
24450 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
24460 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
24470 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
24480 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
24490 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
244a0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
244b0 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
244c0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
244d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
244e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
244f0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
24500 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
24510 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
24520 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
24530 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
24540 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
24550 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
24560 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
24570 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
24580 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
24590 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
245a0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
245b0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
245c0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
245d0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
245e0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
245f0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
24600 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
24610 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
24620 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
24630 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
24640 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
24650 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
24660 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
24670 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
24680 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
24690 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
246a0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
246b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
246c0 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
246d0 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
246e0 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
246f0 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
24700 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
24710 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
24720 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
24730 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c  irectory].*/.SQL
24740 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
24750 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
24760 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
24770 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
24780 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
24790 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
247a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
247b0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
247c0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
247d0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
247e0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
247f0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
24800 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
24810 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
24820 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
24830 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
24840 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
24850 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
24860 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
24870 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
24880 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
24890 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
248a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
248b0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
248c0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
248d0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
248e0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
248f0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
24900 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
24910 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
24920 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
24930 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
24940 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
24950 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
24960 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
24970 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
24980 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24990 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
249a0 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
249b0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
249c0 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
249d0 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
249e0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
249f0 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
24a00 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
24a10 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
24a20 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
24a30 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
24a40 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
24a50 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
24a60 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
24a70 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
24a80 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
24a90 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
24aa0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
24ab0 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
24ac0 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
24ad0 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
24ae0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24af0 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
24b00 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
24b10 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
24b20 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
24b30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
24b40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
24b50 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
24b60 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
24b70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
24b80 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
24b90 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
24ba0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
24bb0 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
24bc0 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
24bd0 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
24be0 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
24bf0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
24c00 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
24c10 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
24c20 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
24c30 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
24c40 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
24c50 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
24c60 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
24c70 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24c80 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
24c90 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
24ca0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
24cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24cc0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
24cd0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
24ce0 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
24cf0 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
24d00 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
24d10 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
24d20 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
24d30 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
24d40 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
24d50 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
24d60 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
24d70 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
24d80 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
24d90 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
24da0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
24db0 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
24dc0 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
24dd0 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
24de0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
24df0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
24e00 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
24e10 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24e20 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
24e30 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
24e40 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
24e50 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
24e60 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
24e70 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
24e80 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
24e90 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
24ea0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
24eb0 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
24ec0 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
24ed0 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
24ee0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
24ef0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
24f00 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
24f10 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
24f20 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
24f30 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24f40 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
24f50 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
24f60 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
24f70 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
24f80 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
24f90 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
24fa0 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
24fb0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
24fc0 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
24fd0 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
24fe0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
24ff0 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
25000 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
25010 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
25020 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
25030 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
25040 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
25050 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
25060 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
25070 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
25080 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
25090 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
250a0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
250b0 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
250c0 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
250d0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
250e0 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
250f0 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
25100 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
25110 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
25120 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
25130 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
25140 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
25150 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
25160 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
25170 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
25180 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  able..*/.SQLITE_
25190 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
251a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
251b0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
251c0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
251d0 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
251e0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
251f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
25200 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
25210 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
25220 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
25230 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
25240 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
25250 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f  efault);.SQLITE_
25260 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
25270 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
25280 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
25290 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
252a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
252b0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
252c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
252d0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
252e0 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
252f0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
25300 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
25310 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
25320 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
25330 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
25340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25350 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
25360 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
25370 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
25380 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
25390 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
253a0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
253b0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
253c0 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
253d0 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65   call..** If the
253e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
253f0 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73   call was succes
25400 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  sful,.** then th
25410 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
25420 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
25430 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
25440 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
25450 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
25460 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
25470 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
25480 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
25490 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
254a0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
254b0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
254c0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
254d0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
254e0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
254f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25500 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
25510 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
25520 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
25530 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
25540 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
25550 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
25560 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
25570 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
25580 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
25590 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
255a0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
255b0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
255c0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
255d0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
255e0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
255f0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
25600 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
25610 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
25620 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
25630 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
25640 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
25650 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
25660 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
25670 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
25680 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
25690 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
256a0 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
256b0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
256c0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
256d0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
256e0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
256f0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
25700 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
25710 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
25720 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
25730 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
25740 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
25750 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
25760 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
25770 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
25780 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
25790 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
257a0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
257b0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
257c0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
257d0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
257e0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
257f0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
25800 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
25810 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
25820 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
25830 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
25840 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
25850 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
25860 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
25870 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
25880 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
25890 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
258a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
258b0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
258c0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
258d0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
258e0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
258f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
25900 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
25910 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
25920 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
25930 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
25940 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
25950 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
25960 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
25970 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
25980 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
25990 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
259a0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
259b0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
259c0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
259d0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
259e0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
259f0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
25a00 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
25a10 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
25a20 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
25a30 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
25a40 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
25a50 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
25a60 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
25a70 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
25a80 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
25a90 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51  ot be set..*/.SQ
25aa0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
25ab0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
25ac0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
25ad0 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
25ae0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
25af0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
25b00 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
25b10 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
25b20 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
25b30 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
25b40 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72  CALL sqlite3_err
25b50 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  msg(sqlite3*);.S
25b60 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
25b70 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
25b80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72  CALL sqlite3_err
25b90 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
25ba0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
25bb0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
25bc0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
25bd0 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
25be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
25bf0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
25c00 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
25c10 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
25c20 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
25c30 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
25c40 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
25c50 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
25c60 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
25c70 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
25c80 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65  t that.** has be
25c90 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  en compiled into
25ca0 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64   binary form and
25cb0 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
25cc0 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  evaluated..**.**
25cd0 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53   Think of each S
25ce0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
25cf0 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75  a separate compu
25d00 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68  ter program.  Th
25d10 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
25d20 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65  L text is source
25d30 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72   code.  A prepar
25d40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
25d50 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63  ect .** is the c
25d60 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63  ompiled object c
25d70 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75  ode.  All SQL mu
25d80 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
25d90 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72  into a.** prepar
25da0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66  ed statement bef
25db0 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75  ore it can be ru
25dc0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  n..**.** The lif
25dd0 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65  e-cycle of a pre
25de0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
25df0 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67  object usually g
25e00 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  oes like this:.*
25e10 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
25e20 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65  > Create the pre
25e30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
25e40 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
25e50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
25e60 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ()]..** <li> Bin
25e70 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72  d values to [par
25e80 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
25e90 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25ea0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
25eb0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
25ec0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
25ed0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
25ee0 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
25ef0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
25f00 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65  i> Reset the pre
25f10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
25f20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
25f30 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
25f40 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
25f50 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
25f60 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
25f70 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
25f80 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
25f90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
25fa0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
25fb0 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  /ol>.*/.typedef 
25fc0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
25fd0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
25fe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25ff0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
26000 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ts.** METHOD: sq
26010 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lite3.**.** ^(Th
26020 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
26030 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
26040 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
26050 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
26060 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
26070 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
26080 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
26090 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
260a0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
260b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
260c0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
260d0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
260e0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
260f0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
26100 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
26110 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
26120 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
26130 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
26140 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
26150 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
26160 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
26170 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
26180 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
26190 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
261a0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
261b0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
261c0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
261d0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
261e0 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
261f0 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
26200 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
26210 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
26220 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
26230 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
26240 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
26250 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
26260 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
26270 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
26280 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
26290 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
262a0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
262b0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
262c0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
262d0 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
262e0 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
262f0 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
26300 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
26310 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
26320 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
26330 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
26340 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
26350 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
26360 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
26370 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
26380 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
26390 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
263a0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
263b0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
263c0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
263d0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
263e0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
263f0 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
26400 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
26410 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
26420 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
26430 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
26440 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
26450 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
26460 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
26470 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
26480 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
26490 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
264a0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
264b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
264c0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
264d0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
264e0 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
264f0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
26500 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
26510 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
26520 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
26530 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
26540 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
26550 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
26560 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
26570 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
26580 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
26590 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
265a0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
265b0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
265c0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
265d0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
265e0 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
265f0 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
26600 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
26610 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
26620 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
26630 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
26640 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
26650 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
26660 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
26670 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
26680 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
26690 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
266a0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
266b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
266c0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
266d0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
266e0 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
266f0 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
26700 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
26710 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
26720 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
26730 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
26740 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
26750 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
26760 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
26770 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
26780 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
26790 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
267a0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
267b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
267c0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
267d0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
267e0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
267f0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
26800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
26810 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
26820 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
26830 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
26840 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
26850 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
26860 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
26870 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
26880 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
26890 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
268a0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
268b0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
268c0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
268d0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
268e0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
268f0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
26900 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
26910 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
26920 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
26930 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
26940 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
26950 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
26960 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
26970 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
26980 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26990 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
269a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
269b0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
269c0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
269d0 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
269e0 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
269f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26a00 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
26a10 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26a20 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
26a30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26a40 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
26a50 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
26a60 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
26a70 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26a80 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
26a90 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26aa0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
26ab0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26ac0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
26ad0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
26ae0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
26af0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
26b00 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
26b10 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
26b20 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
26b30 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
26b40 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
26b50 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
26b60 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
26b70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26b80 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
26b90 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26ba0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
26bb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26bc0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
26bd0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
26be0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
26bf0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26c00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
26c10 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
26c20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26c30 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
26c40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26c50 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26c60 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
26c70 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
26c80 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
26c90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26ca0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
26cb0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26cc0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
26cd0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26ce0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
26cf0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
26d00 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
26d10 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
26d20 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
26d30 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
26d40 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
26d50 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
26d60 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
26d70 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
26d80 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
26d90 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
26da0 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
26db0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26dc0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
26dd0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26de0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
26df0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
26e00 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26e10 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
26e20 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
26e30 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26e40 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
26e50 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
26e60 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
26e70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26e80 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26e90 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
26ea0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
26eb0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
26ec0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
26ed0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
26ee0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
26ef0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
26f00 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
26f10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26f20 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
26f30 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
26f40 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
26f50 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
26f60 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
26f70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26f80 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
26f90 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
26fa0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
26fb0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
26fc0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26fd0 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
26fe0 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
26ff0 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
27000 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
27010 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27020 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
27030 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27040 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
27050 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
27060 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
27070 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
27080 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
27090 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
270a0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
270b0 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
270c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
270d0 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
270e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
270f0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
27100 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
27110 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
27120 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
27130 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
27140 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
27150 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
27160 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
27170 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
27180 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
27190 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
271a0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
271b0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
271c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
271d0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
271e0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
271f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27200 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
27210 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
27220 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27230 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
27240 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
27250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27260 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
27270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
27280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27290 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
272a0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
272b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
272c0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
272d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
272e0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
272f0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
27300 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
27310 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
27320 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
27330 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
27340 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
27350 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
27360 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
27370 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
27380 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
27390 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
273a0 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
273b0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
273c0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
273d0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
273e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
273f0 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
27400 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
27410 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
27420 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
27430 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
27440 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
27450 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
27460 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
27470 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
27480 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
27490 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
274a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
274b0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
274c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
274d0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
274e0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
274f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
27500 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
27510 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
27520 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
27530 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
27540 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
27550 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
27560 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
27570 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
27580 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
27590 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
275a0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
275b0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
275c0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
275d0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
275e0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
275f0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
27600 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
27610 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
27620 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
27630 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
27640 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27650 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
27660 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
27670 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
27680 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
27690 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
276a0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
276b0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
276c0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
276d0 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
276e0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
276f0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
27700 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
27710 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
27720 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
27730 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
27740 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
27750 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
27760 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
27770 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
27780 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
27790 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
277a0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
277b0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
277c0 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
277d0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
277e0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
277f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
27800 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
27810 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
27820 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
27830 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
27840 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
27850 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
27860 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
27870 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
27880 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
27890 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
278a0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
278b0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
278c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
278d0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
278e0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
278f0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
27900 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
27910 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
27920 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
27930 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
27940 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
27950 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
27960 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
27970 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
27980 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
27990 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
279a0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
279b0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
279c0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
279d0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
279e0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
279f0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
27a00 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
27a10 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
27a20 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
27a30 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
27a40 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
27a50 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
27a60 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
27a70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
27a80 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
27a90 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
27aa0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
27ab0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
27ac0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
27ad0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
27ae0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
27af0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
27b00 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
27b10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
27b20 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
27b30 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
27b40 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
27b50 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
27b60 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
27b70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27b80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27b90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
27ba0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
27bb0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
27bc0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
27bd0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
27be0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
27bf0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
27c00 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
27c10 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
27c20 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
27c30 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
27c40 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
27c50 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
27c60 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
27c70 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
27c80 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
27c90 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
27ca0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
27cb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
27cc0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
27cd0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
27ce0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
27cf0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
27d00 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
27d10 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
27d20 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
27d30 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
27d40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
27d50 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
27d60 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
27d70 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
27d80 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
27d90 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
27da0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27db0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
27dc0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
27dd0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
27de0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
27df0 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
27e00 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
27e10 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
27e20 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
27e30 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
27e40 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
27e50 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
27e60 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
27e70 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
27e80 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
27e90 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
27ea0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
27eb0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
27ec0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
27ed0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
27ee0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
27ef0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
27f00 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
27f10 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
27f20 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
27f30 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
27f40 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
27f50 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
27f60 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
27f70 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
27f80 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
27f90 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
27fa0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
27fb0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
27fc0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
27fd0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
27fe0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
27ff0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
28000 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
28010 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
28020 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
28030 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
28040 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
28050 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
28060 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
28070 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
28080 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
28090 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
280a0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
280b0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
280c0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
280d0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
280e0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
280f0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
28100 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
28110 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
28120 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
28130 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
28140 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
28150 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
28160 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
28170 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
28180 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
28190 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
281a0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
281b0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
281c0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
281d0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
281e0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
281f0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
28200 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
28210 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
28220 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
28230 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
28240 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
28250 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
28260 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
28270 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
28280 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
28290 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
282a0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
282b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
282c0 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
282d0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
282e0 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
282f0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
28300 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
28310 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
28320 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
28330 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28340 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
28350 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28360 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
28370 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
28380 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
28390 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
283a0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
283b0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
283c0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
283d0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
283e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
283f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28400 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28410 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
28420 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
28430 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28440 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
28450 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
28460 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
28470 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
28480 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
28490 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
284a0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
284b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
284c0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
284d0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
284e0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
284f0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
28500 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
28510 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28520 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28530 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28540 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28550 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28560 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28570 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
28580 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
28590 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
285a0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
285b0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
285c0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
285d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
285e0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
285f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28600 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28610 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28620 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
28630 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28640 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
28650 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
28660 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
28670 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28680 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28690 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
286a0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
286b0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
286c0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
286d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
286e0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
286f0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28700 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
28710 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
28720 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
28730 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
28740 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
28750 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
28760 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
28770 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
28780 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
28790 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
287a0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
287b0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
287c0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
287d0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
287e0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
287f0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
28800 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
28810 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
28820 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
28830 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
28840 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
28850 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
28860 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
28870 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
28880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
28890 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
288a0 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t SQL.** METHOD:
288b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
288c0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
288d0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
288e0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
288f0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
28900 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
28910 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
28920 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
28930 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
28940 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
28950 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
28960 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
28970 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28980 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
28990 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
289a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
289b0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
289c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
289d0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
289e0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
289f0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
28a00 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
28a10 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
28a20 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d  he Database.** M
28a30 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
28a40 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
28a50 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
28a60 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
28a70 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
28a80 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
28a90 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
28aa0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28ab0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
28ac0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
28ad0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
28ae0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
28af0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
28b00 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
28b10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
28b20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
28b30 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
28b40 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
28b50 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
28b60 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
28b70 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
28b80 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
28b90 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
28ba0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
28bb0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
28bc0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
28bd0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
28be0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
28bf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
28c00 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
28c10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
28c20 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
28c30 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
28c40 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
28c50 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
28c60 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
28c70 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
28c80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
28c90 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
28ca0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
28cb0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
28cc0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
28cd0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
28ce0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
28cf0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
28d00 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
28d10 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
28d20 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
28d30 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
28d40 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
28d50 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
28d60 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
28d70 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
28d80 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
28d90 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
28da0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
28db0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
28dc0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
28dd0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
28de0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
28df0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
28e00 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
28e10 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
28e20 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
28e30 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
28e40 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
28e50 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
28e60 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
28e70 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
28e80 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
28e90 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
28ea0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
28eb0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
28ec0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
28ed0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
28ee0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
28ef0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28f00 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
28f10 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
28f20 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
28f30 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
28f40 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
28f50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
28f60 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
28f70 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
28f80 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
28f90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
28fa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
28fb0 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
28fc0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
28fd0 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
28fe0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
28ff0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
29000 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
29010 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
29020 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
29030 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
29040 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
29050 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
29060 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
29070 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
29080 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
29090 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
290a0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
290b0 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
290c0 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
290d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
290e0 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
290f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
29100 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
29110 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
29120 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
29130 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
29140 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
29150 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
29160 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
29170 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
29180 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
29190 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
291a0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
291b0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
291c0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
291d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
291e0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
291f0 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
29200 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
29210 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
29220 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
29230 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
29240 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
29250 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
29260 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
29270 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
29280 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
29290 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
292a0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
292b0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
292c0 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
292d0 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
292e0 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
292f0 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
29300 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
29310 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
29320 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
29330 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
29340 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
29350 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29360 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
29370 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
29380 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
29390 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
293a0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
293b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
293c0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
293d0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
293e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
293f0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
29400 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
29410 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
29420 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
29430 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
29440 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
29450 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
29460 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
29470 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
29480 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29490 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
294a0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
294b0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
294c0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
294d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
294e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
294f0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
29500 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
29510 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
29520 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
29530 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
29540 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29550 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
29560 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
29570 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
29580 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
29590 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
295a0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
295b0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
295c0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
295d0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
295e0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
295f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
29600 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
29610 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29620 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
29630 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
29640 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
29650 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
29660 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
29670 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
29680 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
29690 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
296a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
296b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
296c0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
296d0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
296e0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
296f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29700 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
29710 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
29720 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
29730 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
29740 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
29750 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
29760 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
29770 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
29780 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
29790 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
297a0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
297b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
297c0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
297d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
297e0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
297f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
29800 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
29810 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
29820 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
29830 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
29840 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
29850 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
29860 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
29870 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
29880 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
29890 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
298a0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
298b0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
298c0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
298d0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
298e0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
298f0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
29900 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
29910 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
29920 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
29930 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
29940 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
29950 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
29960 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
29970 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
29980 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
29990 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
299a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
299b0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
299c0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
299d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
299e0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
299f0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
29a00 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
29a10 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
29a20 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
29a30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29a40 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
29a50 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
29a60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
29a70 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
29a80 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
29a90 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
29aa0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
29ab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
29ac0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
29ad0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
29ae0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
29af0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29b00 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
29b10 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
29b20 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
29b30 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
29b40 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
29b50 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
29b60 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
29b70 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
29b80 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
29b90 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
29ba0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
29bb0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
29bc0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
29bd0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
29be0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
29bf0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
29c00 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
29c10 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
29c20 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
29c30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29c40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
29c50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
29c60 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
29c70 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
29c80 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
29c90 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
29ca0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
29cb0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
29cc0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
29cd0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
29ce0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
29cf0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
29d00 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
29d10 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
29d20 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
29d30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
29d40 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
29d50 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
29d60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
29d70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
29d80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29d90 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
29da0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
29db0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
29dc0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
29dd0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
29de0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
29df0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
29e00 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
29e10 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
29e20 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
29e30 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
29e40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
29e50 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
29e60 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
29e70 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
29e80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29e90 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
29ea0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
29eb0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
29ec0 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
29ed0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
29ee0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
29ef0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
29f00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
29f10 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
29f20 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
29f30 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
29f40 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
29f50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
29f60 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
29f70 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
29f80 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
29f90 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
29fa0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
29fb0 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
29fc0 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
29fd0 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
29fe0 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
29ff0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2a000 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2a010 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2a020 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2a030 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2a040 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2a050 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2a060 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2a070 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2a080 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2a090 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2a0a0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2a0b0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2a0c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2a0d0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2a0e0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2a0f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a100 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2a110 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2a120 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2a130 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2a140 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2a150 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2a160 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2a170 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2a180 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2a190 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2a1a0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2a1b0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2a1c0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2a1d0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2a1e0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2a1f0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2a200 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2a210 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2a220 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2a230 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2a240 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2a250 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2a260 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a270 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2a280 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2a290 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2a2a0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2a2b0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2a2c0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2a2d0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2a2e0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2a2f0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2a300 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2a310 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2a320 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2a330 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2a340 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2a350 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2a360 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2a370 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2a380 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2a390 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2a3a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2a3b0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2a3c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a3d0 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2a3e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2a3f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2a400 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2a410 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2a420 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2a430 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2a440 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2a450 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2a460 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2a470 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2a480 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2a490 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2a4a0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2a4b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2a4c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2a4d0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2a4e0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2a4f0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2a500 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2a510 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2a520 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2a530 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2a540 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2a550 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2a560 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2a570 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2a580 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2a590 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2a5a0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2a5b0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2a5c0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2a5d0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2a5e0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2a5f0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2a600 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2a610 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2a620 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2a630 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2a640 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2a650 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2a660 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a670 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2a680 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2a690 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2a6a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2a6b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2a6c0 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2a6d0 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2a6e0 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2a6f0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2a700 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2a710 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2a720 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2a730 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2a740 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2a750 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2a760 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2a770 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2a780 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2a790 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2a7a0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2a7b0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2a7c0 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2a7d0 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2a7e0 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2a7f0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2a800 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2a810 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2a820 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2a830 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2a840 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2a850 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2a860 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2a870 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2a880 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2a890 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2a8a0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2a8b0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2a8c0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2a8d0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2a8e0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2a8f0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2a900 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2a910 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2a920 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2a930 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2a940 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2a950 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2a960 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2a970 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2a980 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2a990 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2a9a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2a9b0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2a9c0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2a9d0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2a9e0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2a9f0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2aa00 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2aa10 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2aa20 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2aa30 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2aa40 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2aa50 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2aa60 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2aa70 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2aa80 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2aa90 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2aaa0 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2aab0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2aac0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2aad0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2aae0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2aaf0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2ab00 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2ab10 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2ab20 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2ab30 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2ab40 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2ab50 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2ab60 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2ab70 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2ab80 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2ab90 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2aba0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2abb0 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2abc0 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2abd0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2abe0 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2abf0 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2ac00 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2ac10 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2ac20 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2ac30 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2ac40 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2ac50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2ac60 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2ac70 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2ac80 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2ac90 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2aca0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2acb0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2acc0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2acd0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2ace0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2acf0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2ad00 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2ad10 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2ad20 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2ad30 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2ad40 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2ad50 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2ad60 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2ad70 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2ad80 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2ad90 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2ada0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2adb0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2adc0 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2add0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2ade0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2adf0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2ae00 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2ae10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ae20 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2ae30 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2ae40 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2ae50 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ae60 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2ae70 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2ae80 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2ae90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2aea0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2aeb0 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2aec0 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2aed0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2aee0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2aef0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2af00 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2af10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2af20 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2af30 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2af40 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2af50 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2af60 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2af70 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2af80 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2af90 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2afa0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2afb0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2afc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2afd0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2afe0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2aff0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2b000 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2b010 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2b020 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2b030 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2b040 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2b050 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2b060 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2b070 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2b080 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2b090 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2b0a0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2b0b0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2b0c0 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2b0d0 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2b0e0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2b0f0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2b100 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2b110 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2b120 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2b130 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2b140 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2b150 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2b160 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2b170 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2b180 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2b190 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2b1a0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2b1b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2b1c0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2b1d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b1e0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2b1f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2b200 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2b210 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2b220 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2b230 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2b240 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2b250 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2b260 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
2b270 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2b280 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b290 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b2a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28  te3_bind_blob64(
2b2b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b2c0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2b2d0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2b2e0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2b2f0 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
2b300 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2b310 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2b320 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2b330 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
2b340 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b350 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
2b360 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b370 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2b380 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
2b390 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
2b3a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b3b0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2b3c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2b3d0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2b3e0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2b3f0 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
2b400 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2b410 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2b420 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
2b430 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  tmt*, int);.SQLI
2b440 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2b450 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2b460 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2b470 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2b480 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2b490 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
2b4a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b4b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b4c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2b4d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b4e0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2b4f0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2b500 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2b510 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b520 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b530 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
2b540 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b550 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
2b560 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2b570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b580 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2b590 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
2b5a0 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 4c  r encoding);.SQL
2b5b0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2b5c0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2b5d0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
2b5e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b5f0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
2b600 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2b610 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b620 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2b630 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
2b640 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b650 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2b660 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2b670 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2b680 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
2b690 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2b6a0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
2b6b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2b6c0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
2b6d0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
2b6e0 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
2b6f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2b700 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
2b710 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
2b720 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
2b730 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
2b740 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
2b750 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
2b760 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
2b770 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
2b780 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
2b790 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
2b7a0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
2b7b0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
2b7c0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
2b7d0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
2b7e0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
2b7f0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
2b800 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
2b810 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
2b820 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
2b830 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
2b840 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
2b850 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2b860 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
2b870 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
2b880 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
2b890 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
2b8a0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
2b8b0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
2b8c0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
2b8d0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2b8e0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2b8f0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2b900 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b910 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
2b920 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b930 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b940 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2b950 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2b960 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2b970 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2b980 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
2b990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b9a0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
2b9b0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
2b9c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2b9d0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2b9e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b9f0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
2ba00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ba10 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
2ba20 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
2ba30 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2ba40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ba50 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
2ba60 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
2ba70 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
2ba80 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2ba90 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2baa0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
2bab0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
2bac0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2bad0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2bae0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
2baf0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
2bb00 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
2bb10 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
2bb20 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
2bb30 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
2bb40 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
2bb50 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
2bb60 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2bb70 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
2bb80 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
2bb90 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
2bba0 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
2bbb0 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
2bbc0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
2bbd0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
2bbe0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
2bbf0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
2bc00 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
2bc10 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
2bc20 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
2bc30 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
2bc40 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
2bc50 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
2bc60 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
2bc70 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
2bc80 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2bc90 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
2bca0 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
2bcb0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
2bcc0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
2bcd0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
2bce0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
2bcf0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
2bd00 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
2bd10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2bd20 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2bd30 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2bd40 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2bd50 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2bd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2bd70 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2bd80 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2bd90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2bda0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2bdb0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2bdc0 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
2bdd0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2bde0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2bdf0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2be00 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2be10 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2be20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2be30 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2be40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2be50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2be60 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2be70 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2be80 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2be90 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2bea0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2beb0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2bec0 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2bed0 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2bee0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2bef0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2bf00 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2bf10 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2bf20 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2bf30 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2bf40 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2bf50 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2bf60 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2bf70 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2bf80 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2bf90 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2bfa0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2bfb0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2bfc0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2bfd0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2bfe0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2bff0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2c000 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2c010 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c020 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2c030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2c040 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2c050 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2c060 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2c070 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2c080 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2c090 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
2c0a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2c0b0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
2c0c0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
2c0d0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
2c0e0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2c0f0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2c100 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2c110 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
2c120 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
2c130 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
2c140 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
2c150 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
2c160 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2c170 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
2c180 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c190 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
2c1a0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
2c1b0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
2c1c0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
2c1d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2c1e0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2c1f0 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  L sqlite3_clear_
2c200 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2c210 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2c220 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2c230 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
2c240 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
2c250 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2c260 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
2c270 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2c280 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2c290 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2c2a0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2c2b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c2c0 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2c2d0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2c2e0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2c2f0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2c300 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2c310 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2c320 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2c330 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2c340 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2c350 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2c360 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2c370 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2c380 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2c390 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2c3a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c3b0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2c3c0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2c3d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c3e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c3f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2c400 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2c410 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2c420 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2c430 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2c440 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2c450 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2c460 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2c470 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2c480 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2c490 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2c4a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2c4b0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2c4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c4d0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2c4e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2c4f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2c500 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2c510 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2c520 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2c530 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c540 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2c550 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2c560 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2c570 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2c580 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2c590 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2c5a0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2c5b0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2c5c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2c5d0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2c5e0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2c5f0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2c600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c610 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2c620 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2c630 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2c640 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2c650 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2c660 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2c670 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2c680 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2c690 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2c6a0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2c6b0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2c6c0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2c6d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2c6e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2c6f0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2c700 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2c710 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2c720 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2c730 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2c740 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2c750 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2c760 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2c770 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2c780 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2c790 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2c7a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2c7b0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2c7c0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2c7d0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2c7e0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2c7f0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2c800 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2c810 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2c820 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2c830 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2c840 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2c850 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2c860 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2c870 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2c880 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2c890 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2c8a0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51   the next..*/.SQ
2c8b0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2c8c0 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2c8d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2c8e0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
2c8f0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  stmt*, int N);.S
2c900 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2c910 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
2c920 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2c930 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
2c940 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2c950 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c960 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
2c970 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
2c980 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2c990 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c9a0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2c9b0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2c9c0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2c9d0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2c9e0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2c9f0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2ca00 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2ca10 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2ca20 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2ca30 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2ca40 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2ca50 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2ca60 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2ca70 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2ca80 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2ca90 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2caa0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2cab0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2cac0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2cad0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2cae0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2caf0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2cb00 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2cb10 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2cb20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2cb30 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2cb40 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2cb50 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2cb60 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2cb70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cb80 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2cb90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2cba0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2cbb0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2cbc0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2cbd0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2cbe0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2cbf0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2cc00 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2cc10 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2cc20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2cc30 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2cc40 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2cc50 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2cc60 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2cc70 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2cc80 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2cc90 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2cca0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2ccb0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2ccc0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2ccd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2cce0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2ccf0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2cd00 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2cd10 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2cd20 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2cd30 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2cd40 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2cd50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2cd60 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2cd70 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2cd80 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2cd90 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2cda0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2cdb0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2cdc0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2cdd0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2cde0 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2cdf0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2ce00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2ce10 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2ce20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2ce30 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2ce40 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2ce50 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2ce60 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2ce70 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2ce80 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2ce90 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2cea0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2ceb0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2cec0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2ced0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2cee0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2cef0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2cf00 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2cf10 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2cf20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2cf30 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2cf40 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2cf50 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2cf60 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2cf70 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2cf80 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2cf90 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2cfa0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2cfb0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2cfc0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2cfd0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2cfe0 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2cff0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2d000 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2d010 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2d020 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2d030 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2d040 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2d050 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2d060 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2d070 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2d080 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2d090 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2d0a0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2d0b0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2d0c0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2d0d0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2d0e0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2d0f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2d100 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2d110 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2d120 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2d130 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2d140 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2d150 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2d160 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2d170 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2d180 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2d190 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2d1a0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2d1b0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2d1c0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d1d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2d1e0 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
2d1f0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d200 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2d210 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2d220 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2d230 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2d240 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2d250 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d260 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2d270 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d280 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2d290 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
2d2a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d2b0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2d2c0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2d2d0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2d2e0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
2d2f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2d310 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
2d320 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2d330 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2d340 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2d350 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2d360 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2d370 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d380 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2d390 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  nst void *SQLITE
2d3a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d3b0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2d3c0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2d3d0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2d3e0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2d3f0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2d400 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2d410 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d420 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
2d430 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2d440 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2d450 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2d460 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2d470 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2d480 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2d490 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2d4a0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2d4b0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2d4c0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2d4d0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2d4e0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2d4f0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2d500 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2d510 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2d520 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2d530 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2d540 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2d550 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2d560 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2d570 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2d580 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2d590 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2d5a0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2d5b0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2d5c0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2d5d0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2d5e0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2d5f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2d600 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2d610 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2d620 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2d630 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2d640 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2d650 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2d660 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2d670 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2d680 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2d690 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2d6a0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2d6b0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2d6c0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2d6d0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2d6e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2d6f0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2d700 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2d710 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2d720 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2d730 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2d740 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2d750 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2d760 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2d770 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2d780 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2d790 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2d7a0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2d7b0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2d7c0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2d7d0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2d7e0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2d7f0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2d800 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2d810 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2d820 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2d830 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2d840 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2d850 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2d860 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2d870 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2d880 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2d890 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
2d8a0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2d8b0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
2d8c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d8d0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2d8e0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
2d8f0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d900 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2d910 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2d920 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2d930 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2d940 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2d950 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
2d960 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2d970 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2d980 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2d990 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2d9a0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2d9b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d9c0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2d9d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2d9e0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2d9f0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2da00 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2da10 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2da20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2da30 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2da40 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2da50 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2da60 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2da70 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2da80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2da90 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2daa0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2dab0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2dac0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2dad0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2dae0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2daf0 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2db00 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2db10 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2db20 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2db30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2db40 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2db50 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2db60 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2db70 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2db80 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2db90 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2dba0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2dbb0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2dbc0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2dbd0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2dbe0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2dbf0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2dc00 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2dc10 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2dc20 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2dc30 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2dc40 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2dc50 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2dc60 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2dc70 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2dc80 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2dc90 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2dca0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2dcb0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2dcc0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2dcd0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2dce0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2dcf0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2dd00 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2dd10 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2dd20 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2dd30 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2dd40 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2dd50 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2dd60 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2dd70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2dd80 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2dd90 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2dda0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2ddb0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2ddc0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2ddd0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2dde0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2ddf0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2de00 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2de10 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2de20 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2de30 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2de40 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2de50 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2de60 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2de70 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2de80 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2de90 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2dea0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2deb0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2dec0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2ded0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2dee0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2def0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2df00 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2df10 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2df20 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2df30 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2df40 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2df50 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2df60 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2df70 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2df80 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2df90 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2dfa0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2dfb0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2dfc0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2dfd0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2dfe0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2dff0 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2e000 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2e010 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2e020 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2e030 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2e040 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2e050 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2e060 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2e070 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2e080 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2e090 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2e0a0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2e0b0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2e0c0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2e0d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2e0e0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2e0f0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2e100 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2e110 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2e120 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2e130 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2e140 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2e150 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2e160 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2e170 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2e180 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2e190 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2e1a0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2e1b0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2e1c0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2e1d0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2e1e0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2e1f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2e200 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2e210 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2e220 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2e230 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2e240 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2e250 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2e260 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2e270 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e280 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2e290 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2e2a0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2e2b0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2e2c0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2e2d0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2e2e0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2e2f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2e300 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2e310 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2e320 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2e330 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2e340 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2e350 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2e360 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2e370 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2e380 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2e390 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2e3a0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2e3b0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2e3c0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2e3d0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2e3e0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2e3f0 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2e400 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2e410 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2e420 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2e430 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2e440 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2e450 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2e460 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2e470 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2e480 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2e490 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2e4a0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2e4b0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2e4c0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2e4d0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2e4e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2e4f0 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2e500 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2e510 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2e520 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2e530 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2e540 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2e550 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2e560 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2e570 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2e580 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2e590 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2e5a0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2e5b0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2e5c0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2e5d0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2e5e0 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2e5f0 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2e600 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2e610 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2e620 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2e630 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2e640 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2e650 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2e660 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2e670 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2e680 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2e690 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2e6a0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2e6b0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2e6c0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2e6d0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2e6e0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2e6f0 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2e700 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2e710 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2e720 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2e730 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2e740 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2e750 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2e760 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2e770 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2e780 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2e790 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2e7a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2e7b0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2e7c0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2e7d0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2e7e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2e7f0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2e800 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2e810 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2e820 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2e830 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2e840 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2e850 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2e860 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2e870 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2e880 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2e890 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2e8a0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2e8b0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2e8c0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2e8d0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2e8e0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2e8f0 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2e900 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2e910 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2e920 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2e930 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2e940 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2e950 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2e960 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2e970 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2e980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e990 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2e9a0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2e9b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e9c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2e9d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2e9e0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2e9f0 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2ea00 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2ea10 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2ea20 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2ea30 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2ea40 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2ea50 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2ea60 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2ea70 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2ea80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2ea90 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2eaa0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2eab0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2eac0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2ead0 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2eae0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2eaf0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2eb00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2eb10 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2eb20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2eb30 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2eb40 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2eb50 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2eb60 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2eb70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2eb80 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2eb90 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2eba0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2ebb0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2ebc0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2ebd0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2ebe0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2ebf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2ec00 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2ec10 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2ec20 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2ec30 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2ec40 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2ec50 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2ec60 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2ec70 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2ec80 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
2ec90 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2eca0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
2ecb0 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
2ecc0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
2ecd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2ece0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
2ecf0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
2ed00 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2ed10 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
2ed20 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
2ed30 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
2ed40 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2ed50 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
2ed60 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
2ed70 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
2ed80 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
2ed90 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
2eda0 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
2edb0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
2edc0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
2edd0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
2ede0 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
2edf0 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
2ee00 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
2ee10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2ee20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2ee30 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
2ee40 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2ee50 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2ee60 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2ee70 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2ee80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ee90 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2eea0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2eeb0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2eec0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2eed0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2eee0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2eef0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2ef00 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2ef10 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2ef20 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2ef30 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2ef40 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2ef50 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2ef60 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2ef70 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2ef80 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2ef90 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2efa0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2efb0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2efc0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2efd0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2efe0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2eff0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2f000 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2f010 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2f020 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2f030 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2f040 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2f050 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2f060 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2f070 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2f080 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2f090 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2f0a0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2f0b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2f0c0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2f0d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2f0e0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2f0f0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2f100 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2f110 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2f120 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2f130 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2f140 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2f150 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2f160 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2f170 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2f180 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2f190 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2f1a0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2f1b0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2f1c0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2f1d0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
2f1e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f1f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2f200 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2f210 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2f220 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2f230 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2f240 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2f250 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2f260 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2f270 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2f280 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2f290 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2f2a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2f2b0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2f2c0 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2f2d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2f2e0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2f2f0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2f300 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2f310 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2f320 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2f330 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2f340 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2f350 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2f360 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2f370 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2f380 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2f390 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2f3a0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2f3b0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2f3c0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2f3d0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2f3e0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2f3f0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2f400 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2f410 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2f420 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2f430 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2f440 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2f450 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2f460 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2f470 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2f480 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2f490 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2f4a0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2f4b0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2f4c0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2f4d0 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2f4e0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2f4f0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2f500 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2f510 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2f520 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2f530 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2f540 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2f550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2f560 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2f570 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2f580 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2f590 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2f5a0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2f5b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2f5c0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2f5d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2f5e0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2f5f0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2f600 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f610 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2f620 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2f630 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2f640 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2f650 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2f660 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2f670 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2f680 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2f690 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f6a0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2f6b0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2f6c0 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2f6d0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2f6e0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2f6f0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2f700 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2f710 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f730 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2f740 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2f750 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2f760 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2f770 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2f780 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2f790 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2f7a0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2f7b0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2f7c0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2f7d0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2f7e0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2f7f0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2f800 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2f810 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2f820 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2f830 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2f840 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2f850 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2f860 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2f870 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2f880 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2f890 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2f8a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2f8b0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2f8c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2f8d0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2f8e0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2f8f0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2f900 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2f910 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2f920 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2f930 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2f940 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2f950 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2f960 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2f970 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2f980 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2f990 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f9a0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2f9b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2f9c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f9d0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2f9e0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2f9f0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2fa00 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2fa10 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2fa20 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2fa30 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2fa40 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2fa50 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2fa60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2fa70 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2fa80 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2fa90 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2faa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2fab0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2fac0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2fad0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2fae0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2faf0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2fb00 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2fb10 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2fb20 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2fb30 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2fb40 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2fb50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2fb60 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2fb70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fb80 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2fb90 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2fba0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2fbb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2fbc0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2fbd0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2fbe0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2fbf0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2fc00 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2fc10 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2fc20 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2fc30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fc40 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2fc50 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2fc60 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2fc70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2fc80 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2fc90 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2fca0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2fcb0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2fcc0 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2fcd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2fce0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2fcf0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2fd00 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2fd10 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2fd20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2fd30 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2fd40 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2fd50 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2fd60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2fd70 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2fd80 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2fd90 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2fda0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2fdb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fdc0 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2fdd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fde0 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2fdf0 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2fe00 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2fe10 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2fe20 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2fe30 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2fe40 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2fe50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2fe60 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2fe70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fe80 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2fe90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2fea0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2feb0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2fec0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2fed0 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2fee0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2fef0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2ff00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2ff10 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2ff20 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2ff30 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2ff40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
2ff50 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2ff60 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2ff70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2ff80 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2ff90 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2ffa0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2ffb0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2ffc0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2ffd0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2ffe0 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2fff0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30000 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
30010 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
30020 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
30030 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
30040 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
30050 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
30060 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
30070 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
30080 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
30090 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
300a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
300b0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
300c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
300d0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
300e0 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
300f0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
30100 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
30110 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
30120 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
30130 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30140 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
30150 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
30160 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
30170 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
30180 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
30190 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
301a0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
301b0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
301c0 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
301d0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
301e0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
301f0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
30200 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
30210 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
30220 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
30230 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
30240 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
30250 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
30260 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
30270 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
30280 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
30290 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
302a0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
302b0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
302c0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
302d0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
302e0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
302f0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
30300 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
30310 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
30320 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
30330 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
30340 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
30350 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
30360 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
30370 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
30380 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
30390 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
303a0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
303b0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
303c0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
303d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
303e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
303f0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
30400 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
30410 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
30420 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
30430 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
30440 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
30450 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
30460 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
30470 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
30480 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
30490 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
304a0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
304b0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
304c0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
304d0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
304e0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
304f0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
30500 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30510 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
30520 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
30530 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
30540 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
30550 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
30560 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
30570 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
30580 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
30590 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
305a0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
305b0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
305c0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
305d0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
305e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
305f0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
30600 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
30610 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
30620 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
30630 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
30640 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
30650 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
30660 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
30670 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
30680 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
30690 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
306a0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
306b0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
306c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
306d0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
306e0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
306f0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
30700 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
30710 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
30720 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
30730 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
30740 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
30750 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
30760 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
30770 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
30780 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
30790 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
307a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
307b0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
307c0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
307d0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
307e0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
307f0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
30800 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
30810 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
30820 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
30830 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
30840 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
30850 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
30860 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
30870 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
30880 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
30890 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
308a0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
308b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
308c0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
308d0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
308e0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
308f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
30900 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
30910 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
30920 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
30930 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
30940 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
30950 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
30960 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
30970 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
30980 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30990 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
309a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
309b0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
309c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
309d0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
309e0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
309f0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
30a00 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
30a10 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
30a20 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
30a30 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
30a40 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
30a50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
30a60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
30a70 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
30a80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30a90 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
30aa0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
30ab0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
30ac0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
30ad0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
30ae0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30af0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
30b00 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30b10 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
30b20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
30b30 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
30b40 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
30b50 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
30b60 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
30b70 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
30b80 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
30b90 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
30ba0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
30bb0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
30bc0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
30bd0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
30be0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
30bf0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
30c00 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
30c10 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
30c20 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
30c30 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
30c40 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
30c50 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
30c60 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
30c70 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
30c80 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
30c90 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
30ca0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
30cb0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
30cc0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
30cd0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
30ce0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
30cf0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
30d00 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
30d10 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
30d20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
30d30 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
30d40 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
30d50 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
30d60 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
30d70 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
30d80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30d90 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
30da0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
30db0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
30dc0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
30dd0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
30de0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
30df0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
30e00 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
30e10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30e20 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
30e30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30e40 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
30e50 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
30e60 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
30e70 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
30e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30e90 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
30ea0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
30eb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30ec0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
30ed0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
30ee0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
30ef0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
30f00 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
30f10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
30f20 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
30f30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30f40 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
30f50 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
30f60 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
30f70 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
30f80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
30f90 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
30fa0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
30fb0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
30fc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30fd0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
30fe0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
30ff0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
31000 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
31010 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
31020 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
31030 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
31040 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
31050 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
31060 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
31070 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
31080 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
31090 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
310a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
310b0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
310c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
310d0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
310e0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
310f0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
31100 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
31110 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
31120 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
31130 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
31140 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
31150 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
31160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
31170 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
31180 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
31190 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
311a0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
311b0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
311c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
311d0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
311e0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
311f0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
31200 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
31210 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
31220 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
31230 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
31240 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
31250 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
31260 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
31270 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
31280 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
31290 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
312a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
312b0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
312c0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
312d0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  MEM].)^.*/.SQLIT
312e0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
312f0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
31300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31310 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
31320 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
31330 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
31340 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
31350 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31360 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
31370 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
31380 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
31390 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
313a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
313b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
313c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
313d0 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c  E_API double SQL
313e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
313f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
31400 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31410 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
31420 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
31430 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
31440 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
31450 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31460 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
31470 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
31480 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
31490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
314a0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
314b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
314c0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
314d0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51  nsigned char *SQ
314e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
314f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31500 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31510 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31520 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
31530 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
31540 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31550 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
31560 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31570 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31580 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
31590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
315a0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
315b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
315c0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
315d0 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54  value *SQLITE_ST
315e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
315f0 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
31600 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31610 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
31620 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
31630 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
31640 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53  nt Object.** DES
31650 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
31660 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
31670 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
31680 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
31690 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
316a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
316b0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
316c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
316d0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
316e0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
316f0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
31700 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
31710 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
31720 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
31730 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
31740 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
31750 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
31760 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
31770 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
31780 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
31790 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
317a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
317b0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
317c0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
317d0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
317e0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
317f0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
31800 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31810 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
31820 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
31830 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
31840 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
31850 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
31860 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
31870 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
31880 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
31890 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
318a0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
318b0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
318c0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
318d0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
318e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
318f0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
31900 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
31910 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
31920 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
31930 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
31940 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
31950 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
31960 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
31970 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
31980 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
31990 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
319a0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
319b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
319c0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
319d0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
319e0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
319f0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
31a00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
31a10 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
31a20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
31a30 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
31a40 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
31a50 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
31a60 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
31a70 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
31a80 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
31a90 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
31aa0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
31ab0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
31ac0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
31ad0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
31ae0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
31af0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
31b00 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
31b10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
31b20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
31b30 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
31b40 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
31b50 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
31b60 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f   Object.** METHO
31b70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31b80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
31b90 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
31ba0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
31bb0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
31bc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
31bd0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
31be0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
31bf0 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
31c00 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
31c10 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
31c20 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
31c30 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
31c40 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
31c50 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
31c60 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
31c70 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
31c80 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
31c90 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
31ca0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
31cb0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
31cc0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
31cd0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
31ce0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
31cf0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
31d00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31d10 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
31d20 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
31d30 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
31d40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
31d50 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
31d60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
31d70 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
31d80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31d90 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
31da0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
31db0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
31dc0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
31dd0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
31de0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
31df0 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
31e00 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
31e10 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
31e20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
31e30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
31e40 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
31e50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
31e60 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
31e70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31e80 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
31e90 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
31ea0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
31eb0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
31ec0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
31ed0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
31ee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
31ef0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
31f00 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
31f10 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
31f20 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
31f30 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
31f40 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
31f50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
31f60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
31f70 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
31f80 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  L sqlite3_reset(
31f90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
31fa0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
31fb0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
31fc0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
31fd0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
31fe0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
31ff0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
32000 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
32010 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32020 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
32030 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
32040 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32050 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
32060 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
32070 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
32080 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
32090 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
320a0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
320b0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
320c0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
320d0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
320e0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
320f0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
32100 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
32110 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
32120 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
32130 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
32140 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
32150 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
32160 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
32170 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
32180 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
32190 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
321a0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
321b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
321c0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
321d0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
321e0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
321f0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
32200 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
32210 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32220 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
32230 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
32240 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
32250 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32260 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
32270 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
32280 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
32290 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
322a0 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
322b0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
322c0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
322d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
322e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
322f0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
32300 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
32310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32320 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
32330 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
32340 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32350 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
32360 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
32370 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
32380 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
32390 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
323a0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
323b0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
323c0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
323d0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
323e0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
323f0 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
32400 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
32410 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
32420 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
32430 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
32440 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
32450 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
32460 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
32470 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
32480 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
32490 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
324a0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
324b0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
324c0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
324d0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
324e0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
324f0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
32500 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
32510 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32520 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
32530 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
32540 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
32550 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32560 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
32570 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
32580 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
32590 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
325a0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
325b0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
325c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
325d0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
325e0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
325f0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
32600 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
32610 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
32620 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
32630 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
32640 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
32650 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
32660 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
32670 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
32680 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
32690 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
326a0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
326b0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
326c0 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69  ters.  The appli
326d0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65  cation should se
326e0 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  t this parameter
326f0 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   to.** [SQLITE_U
32700 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66  TF16LE] if the f
32710 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
32720 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a  tation invokes .
32730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
32740 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e  e_text16le()] on
32750 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53   an input, or [S
32760 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69  QLITE_UTF16BE] i
32770 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
32780 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
32790 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
327a0 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e  ext16be()] on an
327b0 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53   input, or.** [S
327c0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20  QLITE_UTF16] if 
327d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
327e0 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64  ext16()] is used
327f0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
32800 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e  8].** otherwise.
32810 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20    ^The same SQL 
32820 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
32830 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
32840 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a  ple times using.
32850 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65  ** different pre
32860 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
32870 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66  dings, with diff
32880 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  erent implementa
32890 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63  tions for.** eac
328a0 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e  h encoding..** ^
328b0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
328c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
328d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
328e0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
328f0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
32900 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
32910 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
32920 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
32930 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
32940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
32950 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  th parameter may
32960 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f   optionally be O
32970 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  Red with [SQLITE
32980 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a  _DETERMINISTIC].
32990 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61  ** to signal tha
329a0 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77  t the function w
329b0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
329c0 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c  n the same resul
329d0 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73  t given.** the s
329e0 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69  ame inputs withi
329f0 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  n a single SQL s
32a00 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20  tatement.  Most 
32a10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  SQL functions ar
32a20 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74  e.** determinist
32a30 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69  ic.  The built-i
32a40 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c  n [random()] SQL
32a50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20   function is an 
32a60 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20  example of a.** 
32a70 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73  function that is
32a80 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74   not determinist
32a90 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ic.  The SQLite 
32aa0 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73  query planner is
32ab0 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66   able to.** perf
32ac0 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f  orm additional o
32ad0 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20  ptimizations on 
32ae0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75  deterministic fu
32af0 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a  nctions, so use.
32b00 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
32b10 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
32b20 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65   flag is recomme
32b30 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69  nded where possi
32b40 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ble..**.** ^(The
32b50 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
32b60 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
32b70 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
32b80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32b90 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
32ba0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
32bb0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
32bc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
32bd0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
32be0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
32bf0 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
32c00 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
32c10 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
32c20 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
32c30 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
32c40 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
32c50 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
32c60 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32c70 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
32c80 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
32c90 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
32ca0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
32cb0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
32cc0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
32cd0 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
32ce0 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
32cf0 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
32d00 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
32d10 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
32d20 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
32d30 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
32d40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32d50 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
32d60 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
32d70 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
32d80 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
32d90 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
32da0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
32db0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
32dc0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
32dd0 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
32de0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
32df0 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
32e00 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
32e10 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
32e20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32e30 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
32e40 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
32e50 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
32e60 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
32e70 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
32e80 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
32e90 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
32ea0 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
32eb0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
32ec0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
32ed0 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
32ee0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
32ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
32f00 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
32f10 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
32f20 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
32f30 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
32f40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32f50 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
32f60 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
32f70 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
32f80 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
32f90 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
32fa0 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
32fb0 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
32fc0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
32fd0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
32fe0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
32ff0 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
33000 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
33010 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
33020 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33030 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
33040 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
33050 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
33060 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
33070 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
33080 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
33090 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
330a0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
330b0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
330c0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
330d0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
330e0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
330f0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
33100 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
33110 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
33120 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
33130 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
33140 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
33150 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
33160 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
33170 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
33180 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
33190 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
331a0 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
331b0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
331c0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
331d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
331e0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
331f0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
33200 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
33210 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
33220 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
33230 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
33240 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
33250 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
33260 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
33270 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
33280 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
33290 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
332a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
332b0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
332c0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
332d0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
332e0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
332f0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
33300 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
33310 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
33320 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
33330 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
33340 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
33350 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
33360 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
33370 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33380 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
33390 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
333a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
333b0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
333c0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
333d0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
333e0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
333f0 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
33400 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
33410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33420 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
33430 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
33440 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
33450 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
33460 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
33470 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
33480 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33490 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
334a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
334b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
334c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
334d0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
334e0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
334f0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
33500 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
33510 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
33520 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33530 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33540 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
33550 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33560 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33570 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
33580 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
33590 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
335a0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
335b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
335c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
335d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
335e0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
335f0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
33600 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
33610 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
33620 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
33630 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
33640 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
33650 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
33660 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
33670 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33680 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
33690 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
336a0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
336b0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
336c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
336d0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
336e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
336f0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
33700 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
33710 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
33720 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
33730 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
33740 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
33750 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
33760 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33770 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33780 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
33790 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
337a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
337b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
337c0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
337d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
337e0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
337f0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
33800 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
33810 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
33820 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
33830 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
33840 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
33850 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
33860 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
33870 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
33880 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
33890 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
338a0 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a           1    /*
338b0 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35   IMP: R-37514-35
338c0 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  566 */.#define S
338d0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
338e0 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50       2    /* IMP
338f0 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20  : R-03371-37637 
33900 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33910 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
33920 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   3    /* IMP: R-
33930 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23  51971-34154 */.#
33940 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
33950 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
33960 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
33970 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
33980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
33990 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
339a0 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a   /* Deprecated *
339b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
339c0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
339d0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
339e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
339f0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
33a00 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
33a10 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54  on Flags.**.** T
33a20 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d  hese constants m
33a30 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74  ay be ORed toget
33a40 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  her with the .**
33a50 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
33a60 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
33a70 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20  ncoding] as the 
33a80 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
33a90 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
33aa0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
33ab0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
33ac0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33ad0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33ae0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33af0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _v2()]..*/.#defi
33b00 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  ne SQLITE_DETERM
33b10 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30  INISTIC    0x800
33b20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33b30 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
33b40 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
33b50 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
33b60 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
33b70 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
33b80 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
33b90 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
33ba0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
33bb0 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
33bc0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
33bd0 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
33be0 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
33bf0 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
33c00 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
33c10 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
33c20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
33c30 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67  ns.  To encourag
33c40 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f  e programmers to
33c50 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20   avoid.** these 
33c60 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69  functions, we wi
33c70 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77  ll not explain w
33c80 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
33c90 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
33ca0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
33cb0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
33cc0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
33cd0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
33ce0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33cf0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
33d00 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
33d10 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
33d20 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54  ECATED int SQLIT
33d30 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33d40 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
33d50 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
33d60 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
33d70 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54  ECATED int SQLIT
33d80 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33d90 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
33da0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
33db0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
33dc0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
33dd0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33de0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
33df0 4c 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  LL sqlite3_globa
33e00 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
33e10 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
33e20 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
33e30 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
33e40 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  L sqlite3_thread
33e50 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
33e60 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
33e70 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33e80 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
33e90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
33ea0 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
33eb0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
33ec0 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20  ,int),.         
33ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
33ee0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
33ef0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
33f00 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
33f10 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
33f20 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
33f30 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
33f40 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a  lite3_value.**.*
33f50 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
33f60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33f70 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
33f80 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
33f90 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
33fa0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
33fb0 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
33fc0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
33fd0 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
33fe0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
33ff0 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
34000 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
34010 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
34020 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
34030 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
34040 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
34050 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34060 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
34070 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34080 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
34090 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
340a0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
340b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
340c0 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
340d0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
340e0 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
340f0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
34100 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
34110 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
34120 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34130 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
34140 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
34150 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
34160 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
34170 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
34180 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
34190 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
341a0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
341b0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
341c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
341d0 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
341e0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
341f0 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
34200 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34210 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
34220 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
34230 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
34240 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
34250 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34260 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
34270 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
34280 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
34290 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
342a0 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
342b0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
342c0 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
342d0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
342e0 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73  except that thes
342f0 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
34300 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
34310 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34320 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
34330 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
34340 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
34350 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
34360 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
34370 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
34380 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
34390 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
343a0 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
343b0 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
343c0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
343d0 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
343e0 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
343f0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
34400 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
34410 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
34420 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
34430 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
34440 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
34450 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
34460 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
34470 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
34480 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
34490 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
344a0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
344b0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
344c0 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
344d0 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
344e0 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
344f0 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
34500 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
34510 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
34520 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
34530 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
34540 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
34550 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
34560 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
34570 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
34580 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
34590 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
345a0 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
345b0 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
345c0 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
345d0 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
345e0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
345f0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
34600 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
34610 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
34620 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
34630 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
34640 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
34650 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
34660 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
34670 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
34680 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
34690 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
346a0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
346b0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
346c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
346d0 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
346e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
346f0 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
34700 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
34710 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
34720 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
34730 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
34740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
34750 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
34760 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
34770 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
34780 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
34790 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
347a0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
347b0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
347c0 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
347d0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
347e0 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
347f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
34800 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
34810 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
34820 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
34830 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
34840 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
34850 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34860 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
34870 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34880 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
34890 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
348a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
348b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
348c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
348d0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
348e0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
348f0 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53   double SQLITE_S
34900 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
34910 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
34920 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
34930 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
34940 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
34950 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
34960 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34970 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
34980 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
34990 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
349a0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
349b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
349c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
349d0 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54  gned char *SQLIT
349e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
349f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
34a00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34a10 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
34a20 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
34a30 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34a40 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
34a50 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
34a60 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
34a70 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
34a80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34a90 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
34aa0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
34ab0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
34ac0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34ad0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34ae0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
34af0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34b00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
34b10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34b20 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
34b30 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
34b40 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
34b50 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
34b60 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
34b70 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34b80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34b90 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
34ba0 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
34bb0 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  text.** METHOD: 
34bc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
34bd0 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
34be0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
34bf0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
34c00 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
34c10 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
34c20 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
34c30 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
34c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
34c50 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
34c60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34c70 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
34c80 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
34c90 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
34ca0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
34cb0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
34cc0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
34cd0 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
34ce0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
34cf0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
34d00 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
34d10 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
34d20 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
34d30 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
34d40 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34d50 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
34d60 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
34d70 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
34d80 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
34d90 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
34da0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
34db0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34dc0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
34dd0 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
34de0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
34df0 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
34e00 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
34e10 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
34e20 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
34e30 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
34e40 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
34e50 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
34e60 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
34e70 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
34e80 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
34e90 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
34ea0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
34eb0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
34ec0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
34ed0 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
34ee0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
34ef0 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
34f00 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34f10 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
34f20 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
34f30 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
34f40 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
34f50 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
34f60 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
34f70 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
34f80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
34f90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
34fa0 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
34fb0 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
34fc0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
34fd0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
34fe0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
34ff0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
35000 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
35010 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
35020 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
35030 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
35040 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
35050 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
35060 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
35070 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
35080 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
35090 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
350a0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
350b0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
350c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
350d0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
350e0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
350f0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
35100 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
35110 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
35120 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
35130 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
35140 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
35150 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
35160 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
35170 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
35180 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35190 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
351a0 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
351b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
351c0 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
351d0 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
351e0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
351f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
35200 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
35210 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35220 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
35230 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
35240 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
35250 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
35260 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
35270 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
35280 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
35290 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
352a0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
352b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
352c0 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
352d0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
352e0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
352f0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
35300 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
35310 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
35320 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
35330 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
35340 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
35350 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
35360 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
35370 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
35380 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
35390 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
353a0 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  LL sqlite3_aggre
353b0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
353c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
353d0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
353e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
353f0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
35400 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
35410 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
35420 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35430 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
35440 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35450 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
35460 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
35470 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
35480 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
35490 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
354a0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
354b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
354c0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
354d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
354e0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
354f0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
35500 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
35510 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35520 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
35530 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
35540 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
35550 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
35560 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
35570 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
35580 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35590 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
355a0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
355b0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
355c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 75 73  DCALL sqlite3_us
355d0 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
355e0 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
355f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
35600 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
35610 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
35620 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
35630 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
35640 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
35650 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
35660 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35670 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
35680 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
35690 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
356a0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
356b0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
356c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
356d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
356e0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
356f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35700 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
35710 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
35720 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
35730 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
35740 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
35750 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
35760 6c 69 74 65 33 20 2a 53 51 4c 49 54 45 5f 53 54  lite3 *SQLITE_ST
35770 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
35780 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
35790 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
357a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
357b0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
357c0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d  iliary Data.** M
357d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
357e0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65  ontext.**.** The
357f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  se functions may
35800 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e   be used by (non
35810 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20  -aggregate) SQL 
35820 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
35830 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
35840 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
35850 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
35860 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
35870 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
35880 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
35890 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
358a0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
358b0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
358c0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
358d0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
358e0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
358f0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
35900 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70  erved.  An examp
35910 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74  le.** of where t
35920 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65  his might be use
35930 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75  ful is in a regu
35940 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
35950 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  atching.** funct
35960 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
35970 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
35980 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
35990 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65  ion can be store
359a0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
359b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
359c0 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
359d0 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61  ing.  .** Then a
359e0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61  s long as the pa
359f0 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d  ttern string rem
35a00 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a  ains the same,.*
35a10 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72  * the compiled r
35a20 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
35a30 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
35a40 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
35a50 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
35a60 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e  e same function.
35a70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35a80 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
35a90 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35aa0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35ab0 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
35ac0 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
35ad0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
35ae0 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
35af0 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
35b00 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
35b10 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
35b20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35b30 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20  tion. ^If there 
35b40 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a  is no metadata.*
35b50 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
35b60 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61  h the function a
35b70 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71  rgument, this sq
35b80 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
35b90 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  a() interface.**
35ba0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
35bb0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
35bc0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
35bd0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
35be0 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
35bf0 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66   P as metadata f
35c00 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
35c10 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
35c20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35c30 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53  ed function.  ^S
35c40 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
35c50 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
35c60 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72  t_auxdata(C,N) r
35c70 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65  eturn P from the
35c80 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
35c90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35ca0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c  ata(C,N,P,X) cal
35cb0 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  l if the metadat
35cc0 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64  a is still valid
35cd0 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74   or.** NULL if t
35ce0 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  he metadata has 
35cf0 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a  been discarded..
35d00 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63  ** ^After each c
35d10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
35d20 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
35d30 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e  ,X) where X is n
35d40 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69  ot NULL,.** SQLi
35d50 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
35d60 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
35d70 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61  nction X with pa
35d80 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c  rameter P exactl
35d90 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20  y.** once, when 
35da0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
35db0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51  discarded..** SQ
35dc0 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
35dd0 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61  discard the meta
35de0 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65  data at any time
35df0 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c  , including: <ul
35e00 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74  >.** <li> when t
35e10 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
35e20 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
35e30 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a  ter changes, or.
35e40 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71  ** <li> when [sq
35e50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
35e60 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
35e70 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
35e80 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
35e90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
35ea0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
35eb0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35ec0 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ata() is invoked
35ed0 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61   again on the sa
35ee0 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  me parameter, or
35ef0 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20  .** <li> during 
35f00 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c  the original sql
35f10 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35f20 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d  () call when a m
35f30 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61  emory .**      a
35f40 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
35f50 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a  occurs. </ul>)^.
35f60 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c  **.** Note the l
35f70 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61  ast bullet in pa
35f80 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64  rticular.  The d
35f90 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a  estructor X in .
35fa0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
35fb0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
35fc0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
35fd0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
35fe0 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  ore the.** sqlit
35ff0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
36000 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20   interface even 
36010 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20  returns.  Hence 
36020 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
36030 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20  ata().** should 
36040 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74  be called near t
36050 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75  he end of the fu
36060 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
36070 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a  ation and the.**
36080 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
36090 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
360a0 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65  not make any use
360b0 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73   of P after.** s
360c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
360d0 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61  ta() has been ca
360e0 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  lled..**.** ^(In
360f0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
36100 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
36110 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
36120 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66  n calls for.** f
36130 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
36140 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70  rs that are comp
36150 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e  ile-time constan
36160 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69  ts, including li
36170 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
36180 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
36190 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73   and expressions
361a0 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74   composed from t
361b0 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a  he same.)^.**.**
361c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
361d0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
361e0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
361f0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
36200 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
36210 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
36220 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36230 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
36240 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
36250 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
36260 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  ext*, int N);.SQ
36270 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
36280 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36290 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
362a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
362b0 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
362c0 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
362d0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
362e0 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
362f0 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
36300 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
36310 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
36320 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
36330 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
36340 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
36350 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
36360 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
36370 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
36380 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
36390 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
363a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
363b0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
363c0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
363d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
363e0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
363f0 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
36400 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
36410 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
36420 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
36430 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
36440 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
36450 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
36460 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
36470 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
36480 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
36490 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
364a0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
364b0 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
364c0 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
364d0 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
364e0 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
364f0 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
36500 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
36510 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
36520 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
36530 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
36540 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
36550 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
36560 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
36570 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
36580 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
36590 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
365a0 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
365b0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
365c0 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
365d0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
365e0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
365f0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
36600 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
36610 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d  QL Function.** M
36620 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
36630 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65  ontext.**.** The
36640 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
36650 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
36660 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
36670 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
36680 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
36690 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
366a0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
366b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
366c0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
366d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
366e0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
366f0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
36700 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
36710 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
36720 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
36730 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
36740 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
36750 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
36760 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
36770 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
36780 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
36790 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
367a0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
367b0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
367c0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
367d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
367e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
367f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36800 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
36810 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
36820 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
36830 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
36840 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36850 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
36860 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
36870 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
36880 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
36890 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
368a0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
368b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
368c0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
368d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
368e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
368f0 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
36900 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
36910 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
36920 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36930 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
36940 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
36950 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
36960 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
36970 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
36980 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
36990 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
369a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
369b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
369c0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
369d0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
369e0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
369f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36a00 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
36a10 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
36a20 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
36a30 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
36a40 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
36a50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36a60 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
36a70 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36a80 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
36a90 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
36aa0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
36ab0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
36ac0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
36ad0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
36ae0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
36af0 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
36b00 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
36b10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36b20 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
36b30 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
36b40 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
36b50 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
36b60 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
36b70 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
36b80 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
36b90 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
36ba0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
36bb0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
36bc0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
36bd0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
36be0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36bf0 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
36c00 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
36c10 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
36c20 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
36c30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
36c40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
36c50 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
36c60 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
36c70 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
36c80 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
36c90 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
36ca0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
36cb0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
36cc0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
36cd0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
36ce0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
36cf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36d00 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
36d10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36d20 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
36d30 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
36d40 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
36d50 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
36d60 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
36d70 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
36d80 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
36d90 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
36da0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36db0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
36dc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36dd0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
36de0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
36df0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
36e00 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
36e10 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
36e20 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
36e30 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
36e40 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
36e50 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
36e60 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
36e70 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
36e80 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
36e90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36ea0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
36eb0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
36ec0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
36ed0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
36ee0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
36ef0 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
36f00 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
36f10 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
36f20 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
36f30 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
36f40 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
36f50 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
36f60 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
36f70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36f80 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
36f90 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
36fa0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
36fb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36fc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
36fd0 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
36fe0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
36ff0 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
37000 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
37010 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
37020 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
37030 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
37040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37050 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
37060 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
37070 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
37080 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65  to throw an.** e
37090 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
370a0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
370b0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
370c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
370d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
370e0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
370f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37100 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
37110 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37120 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
37130 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
37140 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
37150 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
37160 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
37170 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37180 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
37190 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
371a0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
371b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
371c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
371d0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
371e0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
371f0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
37200 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
37210 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
37220 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37230 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
37240 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
37250 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
37260 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37270 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
37280 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
37290 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
372a0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
372b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
372c0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
372d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
372e0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
372f0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
37300 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
37310 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
37320 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
37330 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37340 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
37350 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
37360 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
37370 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
37380 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
37390 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
373a0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
373b0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
373c0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
373d0 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ely..** ^The sql
373e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
373f0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
37400 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
37410 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70  alue of an.** ap
37420 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37430 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37440 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 69   a text string i
37450 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  n an encoding.**
37460 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
37470 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73  e fifth (and las
37480 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68  t) parameter, wh
37490 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a  ich must be one.
374a0 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ** of [SQLITE_UT
374b0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
374c0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
374d0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
374e0 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e  E_UTF16LE]..** ^
374f0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
37500 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
37510 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
37520 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
37530 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
37540 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37550 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
37560 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
37570 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
37580 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
37590 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
375a0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
375b0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
375c0 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
375d0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
375e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
375f0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
37600 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
37610 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
37620 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
37630 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37640 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
37650 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
37660 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
37670 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
37680 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
37690 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
376a0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
376b0 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
376c0 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
376d0 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
376e0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
376f0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
37700 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
37710 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
37720 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
37730 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
37740 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
37750 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
37760 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
37770 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
37780 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
37790 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
377a0 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
377b0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
377c0 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
377d0 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
377e0 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
377f0 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
37800 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
37810 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
37820 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
37830 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
37840 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
37850 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
37860 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
37870 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
37880 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
37890 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
378a0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
378b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
378c0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
378d0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
378e0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
378f0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
37900 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
37910 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
37920 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
37930 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
37940 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
37950 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
37960 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
37970 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
37980 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
37990 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
379a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
379b0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
379c0 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
379d0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
379e0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
379f0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
37a00 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
37a10 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
37a20 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
37a30 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
37a40 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
37a50 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
37a60 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
37a70 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
37a80 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
37a90 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
37aa0 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
37ab0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
37ac0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
37ad0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
37ae0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
37af0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37b00 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
37b10 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
37b20 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
37b30 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
37b40 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
37b50 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
37b60 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
37b70 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
37b80 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
37b90 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
37ba0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
37bb0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
37bc0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
37bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
37be0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
37bf0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
37c00 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
37c10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37c20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
37c30 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
37c40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
37c50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
37c60 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
37c70 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
37c80 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
37c90 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
37ca0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
37cb0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
37cc0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
37cd0 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
37ce0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
37cf0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
37d00 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
37d10 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
37d20 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
37d30 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
37d40 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
37d50 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
37d60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37d70 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37d80 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
37d90 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
37da0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
37db0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37dc0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
37dd0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
37de0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
37df0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
37e00 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
37e10 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
37e20 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
37e30 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
37e40 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
37e50 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
37e60 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
37e70 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
37e80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37e90 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
37ea0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
37eb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
37ec0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
37ed0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
37ee0 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
37ef0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
37f00 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
37f10 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
37f20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
37f30 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
37f40 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
37f50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
37f60 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
37f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37f80 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63  blob64(sqlite3_c
37f90 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f  ontext*,const vo
37fa0 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  id*,.           
37fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37fc0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76  sqlite3_uint64,v
37fd0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37fe0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37ff0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
38000 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
38010 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
38020 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
38030 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
38040 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
38050 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
38060 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
38070 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
38080 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
38090 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
380a0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
380b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
380c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
380d0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
380e0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
380f0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
38100 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  LL sqlite3_resul
38110 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
38120 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
38130 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
38140 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
38150 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38160 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
38170 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
38180 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
38190 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
381a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
381b0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
381c0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
381d0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
381e0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
381f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
38200 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
38210 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
38220 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
38230 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
38240 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
38250 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
38260 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
38270 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
38280 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
38290 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
382a0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
382b0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
382c0 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
382d0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73  CALL sqlite3_res
382e0 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
382f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
38300 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
38310 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
38320 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
38330 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
38340 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38350 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
38360 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
38370 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c  ,sqlite3_uint64,
38380 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
38390 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
383a0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
383b0 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
383c0 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ng);.SQLITE_API 
383d0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
383e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ALL sqlite3_resu
383f0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
38400 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
38410 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
38420 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
38430 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
38440 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
38450 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
38460 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
38470 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
38480 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
38490 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
384a0 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
384b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
384c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
384d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
384e0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
384f0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
38500 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
38510 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
38520 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ALL sqlite3_resu
38530 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
38540 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
38550 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
38560 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
38570 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
38580 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
38590 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
385a0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
385b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
385c0 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
385d0 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 20  ng Sequences.** 
385e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
385f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
38600 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
38610 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
38620 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
38630 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
38640 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
38650 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
38660 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
38670 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
38680 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
38690 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
386a0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
386b0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
386c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
386d0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
386e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
386f0 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
38700 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
38710 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
38720 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38730 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
38740 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
38750 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
38760 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
38770 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
38780 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
38790 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
3