System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact b479b6a7b0fc402946ae0ae2beb878ce6cc33ce2:


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 2e 32 22 0a 23      "3.8.10.2".#
10b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
10c0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30  RSION_NUMBER 300
10d0: 38 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8010.#define SQL
10e0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20  ITE_SOURCE_ID   
10f0: 20 20 20 22 32 30 31 35 2d 30 35 2d 32 30 20 31     "2015-05-20 1
1100: 38 3a 31 37 3a 31 39 20 32 65 66 34 66 33 61 35  8:17:19 2ef4f3a5
1110: 62 31 64 31 64 30 63 34 33 33 38 66 38 32 34 33  b1d1d0c4338f8243
1120: 64 34 30 61 32 34 35 32 63 63 31 66 37 66 65 34  d40a2452cc1f7fe4
1130: 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  "../*.** CAPI3RE
1140: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1150: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1160: 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ers.** KEYWORDS:
1170: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1180: 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  , sqlite3_source
1190: 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  id.**.** These i
11a0: 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64  nterfaces provid
11b0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  e the same infor
11c0: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53  mation as the [S
11d0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a  QLITE_VERSION],.
11e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
11f0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20  ON_NUMBER], and 
1200: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  [SQLITE_SOURCE_I
1210: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  D] C preprocesso
1220: 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20  r macros.** but 
1230: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  are associated w
1240: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20  ith the library 
1250: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68  instead of the h
1260: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43  eader file.  ^(C
1270: 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72  autious.** progr
1280: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63  ammers might inc
1290: 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74  lude assert() st
12a0: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69  atements in thei
12b0: 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  r application to
12c0: 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20  .** verify that 
12d0: 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
12e0: 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  by these interfa
12f0: 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61  ces match the ma
1300: 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68  cros in.** the h
1310: 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20  eader, and thus 
1320: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
1330: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a  application is.*
1340: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
1350: 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79  matching library
1360: 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65   and header file
1370: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s..**.** <blockq
1380: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73  uote><pre>.** as
1390: 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69  sert( sqlite3_li
13a0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
13b0: 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  )==SQLITE_VERSIO
13c0: 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61  N_NUMBER );.** a
13d0: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
13e0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
13f0: 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  ,SQLITE_SOURCE_I
1400: 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65  D)==0 );.** asse
1410: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
1420: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c  e3_libversion(),
1430: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d  SQLITE_VERSION)=
1440: 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  =0 );.** </pre><
1450: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1460: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1470: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1480: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74  ng constant cont
1490: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66  ains the text of
14a0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
14b0: 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68  ].** macro.  ^Th
14c0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14d0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
14e0: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
14f0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74  r to the.** to t
1500: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1510: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1520: 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  tant.  The sqlit
1530: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a  e3_libversion().
1540: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ** function is p
1550: 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20  rovided for use 
1560: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c  in DLLs since DL
1570: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20  L users usually 
1580: 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64  do not have.** d
1590: 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20  irect access to 
15a0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  string constants
15b0: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e   within the DLL.
15c0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
15d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
15e0: 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ber() function r
15f0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
1600: 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53  r equal to.** [S
1610: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1620: 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c  MBER].  ^The sql
1630: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1640: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1650: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
1660: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
1670: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
1680: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
1690: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
16a0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
16b0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a  rocessor macro..
16c0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
16d0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
16e0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
16f0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1700: 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
1710: 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63  E_EXTERN const c
1720: 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73  har sqlite3_vers
1730: 69 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50  ion[];.SQLITE_AP
1740: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
1750: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1760: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1770: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1780: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
1790: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
17a0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f  ite3_sourceid(vo
17b0: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
17c0: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
17d0: 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  LL sqlite3_libve
17e0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
17f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
1800: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1810: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f  brary Compilatio
1820: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f  n Options Diagno
1830: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stics.**.** ^The
1840: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1850: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75  option_used() fu
1860: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30  nction returns 0
1870: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61   or 1 .** indica
1880: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65  ting whether the
1890: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f   specified optio
18a0: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74  n was defined at
18b0: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d   .** compile tim
18c0: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  e.  ^The SQLITE_
18d0: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f   prefix may be o
18e0: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
18f0: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20  .** option name 
1900: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65  passed to sqlite
1910: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1920: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20  used().  .**.** 
1930: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
1940: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1950: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73   function allows
1960: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76   iterating.** ov
1970: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f  er the list of o
1980: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65  ptions that were
1990: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70   defined at comp
19a0: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72  ile time by.** r
19b0: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74  eturning the N-t
19c0: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f  h compile time o
19d0: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e  ption string.  ^
19e0: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  If N is out of r
19f0: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ange,.** sqlite3
1a00: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a10: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  et() returns a N
1a20: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
1a30: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70  he SQLITE_ .** p
1a40: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64  refix is omitted
1a50: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67   from any string
1a60: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  s returned by .*
1a70: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
1a80: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a  eoption_get()..*
1a90: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f  *.** ^Support fo
1aa0: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63  r the diagnostic
1ab0: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74   functions sqlit
1ac0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1ad0: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73  _used().** and s
1ae0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1af0: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62  tion_get() may b
1b00: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65  e omitted by spe
1b10: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20  cifying the .** 
1b20: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d  [SQLITE_OMIT_COM
1b30: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b40: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70  ] option at comp
1b50: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile time..**.** 
1b60: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75  See also: SQL fu
1b70: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f  nctions [sqlite_
1b80: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1b90: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1ba0: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
1bb0: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68  on_get()] and th
1bc0: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f  e [compile_optio
1bd0: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23  ns pragma]..*/.#
1be0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
1bf0: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
1c00: 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50  _DIAGS.SQLITE_AP
1c10: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1c20: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d  CALL sqlite3_com
1c30: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1c40: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74  const char *zOpt
1c50: 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  Name);.SQLITE_AP
1c60: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
1c70: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1c80: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1c90: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1ca0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1cb0: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1cc0: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1cd0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1ce0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cf0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1d00: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1d10: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1d20: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1d30: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1d40: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1d50: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1d60: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1d70: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1d80: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1d90: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1da0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1db0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1dc0: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1dd0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1de0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1df0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1e00: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1e10: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1e20: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1e30: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1e40: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1e50: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1e60: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1e70: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1e80: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1e90: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1ea0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1eb0: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1ec0: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1ed0: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1ee0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1ef0: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1f00: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1f10: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1f20: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1f30: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1f40: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1f50: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1f60: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1f70: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1f80: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1f90: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1fa0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1fb0: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1fc0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1fd0: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1fe0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1ff0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
2000: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
2010: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2020: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
2030: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
2040: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
2050: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
2060: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
2070: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
2080: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
2090: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
20a0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
20b0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
20c0: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
20d0: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
20e0: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
20f0: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2100: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2110: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2120: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2130: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2140: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
2150: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
2160: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
2170: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
2180: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
2190: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
21a0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
21b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
21c0: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
21d0: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
21e0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
21f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2200: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2210: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2220: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2230: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2240: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
2250: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2260: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
2270: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
2280: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
2290: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
22a0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
22b0: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
22c0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
22d0: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
22e0: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
22f0: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2300: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2310: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2320: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2330: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2340: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
2350: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
2360: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
2370: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
2380: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
2390: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
23a0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
23b0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
23c0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
23d0: 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  e(void);../*.** 
23e0: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
23f0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61  se Connection Ha
2400: 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ndle.** KEYWORDS
2410: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  : {database conn
2420: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73  ection} {databas
2430: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a  e connections}.*
2440: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
2450: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
2460: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
2470: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
2480: 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20   instance of.** 
2490: 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63  the opaque struc
24a0: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69  ture named "sqli
24b0: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65  te3".  It is use
24c0: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20  ful to think of 
24d0: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f  an sqlite3.** po
24e0: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65  inter as an obje
24f0: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ct.  The [sqlite
2500: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2510: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
2520: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  nd.** [sqlite3_o
2530: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
2540: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e  aces are its con
2550: 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b  structors, and [
2560: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2570: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2580: 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65  _close_v2()] are
2590: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73   its destructors
25a0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
25b0: 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72  y other.** inter
25c0: 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a  faces (such as.*
25d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
25e0: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
25f0: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2600: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
2610: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
2620: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
2630: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
2640: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e  re methods on an
2650: 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65  .** sqlite3 obje
2660: 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ct..*/.typedef s
2670: 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71  truct sqlite3 sq
2680: 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lite3;../*.** CA
2690: 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49  PI3REF: 64-Bit I
26a0: 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20  nteger Types.** 
26b0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
26c0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
26d0: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
26e0: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
26f0: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
2700: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
2710: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
2720: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
2730: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
2740: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
2750: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
2760: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
2770: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
2780: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
2790: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
27a0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
27b0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
27c0: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
27d0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
27e0: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
27f0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
2800: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
2810: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nly..**.** ^The 
2820: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2830: 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74  d sqlite_int64 t
2840: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
2850: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a  nteger values.**
2860: 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37   between -922337
2870: 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e  2036854775808 an
2880: 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34  d +9223372036854
2890: 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65  775807 inclusive
28a0: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
28b0: 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71  e3_uint64 and sq
28c0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
28d0: 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65  s can store inte
28e0: 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62  ger values .** b
28f0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38  etween 0 and +18
2900: 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36  4467440737095516
2910: 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f  15 inclusive..*/
2920: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49  .#ifdef SQLITE_I
2930: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65  NT64_TYPE.  type
2940: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2950: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74  _TYPE sqlite_int
2960: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2970: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e  signed SQLITE_IN
2980: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
2990: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65  uint64;.#elif de
29a0: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20  fined(_MSC_VER) 
29b0: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52  || defined(__BOR
29c0: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64  LANDC__).  typed
29d0: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ef __int64 sqlit
29e0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
29f0: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e  ef unsigned __in
2a00: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
2a10: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64  4;.#else.  typed
2a20: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ef long long int
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2a50: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  d long long int 
2a60: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2a70: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71  endif.typedef sq
2a80: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
2a90: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65  e3_int64;.typede
2aa0: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  f sqlite_uint64 
2ab0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a  sqlite3_uint64;.
2ac0: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c  ./*.** If compil
2ad0: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73  ing for a proces
2ae0: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66  sor that lacks f
2af0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75  loating point su
2b00: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69  pport,.** substi
2b10: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72  tute integer for
2b20: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e   floating-point.
2b30: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
2b40: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f  E_OMIT_FLOATING_
2b50: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64  POINT.# define d
2b60: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e  ouble sqlite3_in
2b70: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  t64.#endif../*.*
2b80: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
2b90: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43  ing A Database C
2ba0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53  onnection.** DES
2bb0: 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
2bc0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2bd0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2be0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2bf0: 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2c00: 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66  destructors.** f
2c10: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  or the [sqlite3]
2c20: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c   object..** ^Cal
2c30: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c  ls to sqlite3_cl
2c40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2c50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74  3_close_v2() ret
2c60: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2c70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2c80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2c90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ca0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2cb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2cc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2cd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2ce0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2cf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2d00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2d10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2d20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2d30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2d40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2d50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2d60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2d70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2d80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2d90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2da0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2db0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2dc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2dd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2de0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2df0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20  ments.** and/or 
2e00: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2e10: 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e  e3_backups, then
2e20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2e30: 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73  nnection becomes
2e40: 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20  .** an unusable 
2e50: 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77  "zombie" which w
2e60: 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
2e70: 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  y be deallocated
2e80: 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73   when the.** las
2e90: 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2ea0: 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2eb0: 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71  d or the last sq
2ec0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a  lite3_backup is.
2ed0: 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68  ** finished.  Th
2ee0: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  e sqlite3_close_
2ef0: 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  v2() interface i
2f00: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  s intended for u
2f10: 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20  se with.** host 
2f20: 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61  languages that a
2f30: 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65  re garbage colle
2f40: 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20  cted, and where 
2f50: 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69  the order in whi
2f60: 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  ch.** destructor
2f70: 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20  s are called is 
2f80: 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  arbitrary..**.**
2f90: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
2fa0: 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ould [sqlite3_fi
2fb0: 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2fc0: 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  e] all [prepared
2fd0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a   statements],.**
2fe0: 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
2ff0: 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c  lose | close] al
3000: 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  l [BLOB handles]
3010: 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  , and .** [sqlit
3020: 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68  e3_backup_finish
3030: 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b   | finish] all [
3040: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3050: 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74  objects associat
3060: 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
3070: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3080: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
3090: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
30a0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
30b0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
30c0: 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  2() is called on
30d0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
30e0: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74  nection] that st
30f0: 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74  ill has.** outst
3100: 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64  anding [prepared
3110: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
3120: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
3130: 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d/or.** [sqlite3
3140: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
3150: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73   then it returns
3160: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64   [SQLITE_OK] and
3170: 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f   the deallocatio
3180: 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65  n.** of resource
3190: 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e  s is deferred un
31a0: 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  til all [prepare
31b0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
31c0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a  BLOB handles],.*
31d0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
31e0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61  ackup] objects a
31f0: 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65  re also destroye
3200: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
3210: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
3220: 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68   is destroyed wh
3230: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ile a transactio
3240: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68  n is open,.** th
3250: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  e transaction is
3260: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
3270: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
3280: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  * The C paramete
3290: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
32a0: 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c  ose(C)] and [sql
32b0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29  ite3_close_v2(C)
32c0: 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
32d0: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f  her a NULL.** po
32e0: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c  inter or an [sql
32f0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69  ite3] object poi
3300: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  nter obtained.**
3310: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
3320: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
3330: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
3340: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
3350: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70  v2()], and not p
3360: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64  reviously closed
3370: 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  ..** ^Calling sq
3380: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72  lite3_close() or
3390: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
33a0: 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  2() with a NULL 
33b0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d  pointer.** argum
33c0: 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ent is a harmles
33d0: 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49  s no-op..*/.SQLI
33e0: 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
33f0: 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
3400: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3410: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
3420: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
3430: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
3440: 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  2(sqlite3*);../*
3450: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
3460: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
3470: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
3480: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
3490: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
34a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
34b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
34c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
34d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
34e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
34f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
3500: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
3510: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
3520: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
3530: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
3540: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
3550: 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
3560: 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te3.**.** The sq
3570: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
3580: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
3590: 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20  enience wrapper 
35a0: 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
35b0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
35c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
35d0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
35e0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a  _finalize()],.**
35f0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20   that allows an 
3600: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72  application to r
3610: 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74  un multiple stat
3620: 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a  ements of SQL.**
3630: 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20   without having 
3640: 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20  to use a lot of 
3650: 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e  C code. .**.** ^
3660: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
3670: 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e  () interface run
3680: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55  s zero or more U
3690: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a  TF-8 encoded,.**
36a0: 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
36b0: 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ate SQL statemen
36c0: 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69  ts passed into i
36d0: 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c  ts 2nd argument,
36e0: 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65  .** in the conte
36f0: 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  xt of the [datab
3700: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3710: 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73  passed in as its
3720: 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   1st.** argument
3730: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
3740: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  ack function of 
3750: 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
3760: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3770: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3780: 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  L, then it is in
3790: 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72  voked for each r
37a0: 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d  esult row.** com
37b0: 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65  ing out of the e
37c0: 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61  valuated SQL sta
37d0: 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34  tements.  ^The 4
37e0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  th argument to.*
37f0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3800: 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f   is relayed thro
3810: 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61  ugh to the 1st a
3820: 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a  rgument of each.
3830: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f  ** callback invo
3840: 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65  cation.  ^If the
3850: 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65   callback pointe
3860: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3870: 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20  c().** is NULL, 
3880: 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b  then no callback
3890: 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64   is ever invoked
38a0: 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73   and result rows
38b0: 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e   are.** ignored.
38c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  .**.** ^If an er
38d0: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
38e0: 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20   evaluating the 
38f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
3900: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71  assed into.** sq
3910: 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68  lite3_exec(), th
3920: 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  en execution of 
3930: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
3940: 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a  ement stops and.
3950: 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74  ** subsequent st
3960: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69  atements are ski
3970: 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35  pped.  ^If the 5
3980: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3990: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
39a0: 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  * is not NULL th
39b0: 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73  en any error mes
39c0: 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20  sage is written 
39d0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
39e0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
39f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
3a00: 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20  and passed back 
3a10: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3a20: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f  parameter..** To
3a30: 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65   avoid memory le
3a40: 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61  aks, the applica
3a50: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f  tion should invo
3a60: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
3a70: 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20  ()].** on error 
3a80: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20  message strings 
3a90: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
3aa0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3ab0: 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69  er of.** of sqli
3ac0: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
3ad0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
3ae0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
3af0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
3b00: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
3b10: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3b20: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3b30: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
3b40: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
3b50: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
3b60: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
3b70: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
3b80: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
3b90: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
3ba0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
3bb0: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3bc0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
3bd0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
3be0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3bf0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
3c00: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
3c10: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
3c20: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
3c30: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
3c40: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
3c50: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
3c60: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
3c70: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
3c80: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3c90: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3ca0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
3cb0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
3cc0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
3cd0: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
3ce0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
3cf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3d00: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3d10: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3d20: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
3d30: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
3d40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
3d50: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
3d60: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
3d70: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
3d80: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
3d90: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
3da0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
3db0: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
3dc0: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
3dd0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3de0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
3df0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
3e00: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
3e10: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
3e20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
3e30: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
3e40: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
3e50: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
3e60: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
3e70: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
3e80: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
3e90: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
3ea0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3eb0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
3ec0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
3ed0: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3ee0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3ef0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
3f00: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
3f10: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
3f20: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
3f30: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
3f40: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
3f50: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
3f60: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
3f70: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
3f80: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
3f90: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
3fa0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
3fb0: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
3fc0: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
3fd0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
3fe0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69  plication must i
3ff0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
4000: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4010: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
4020: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
4030: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
4040: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4050: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
4060: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
4070: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61  ot close the [da
4080: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4090: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  n] specified by.
40a0: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20  **      the 1st 
40b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
40c0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
40d0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
40e0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
40f0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
4100: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f  tion must not mo
4110: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61  dify the SQL sta
4120: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73  tement text pass
4130: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20  ed into.**      
4140: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
4150: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  r of sqlite3_exe
4160: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4170: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4180: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ing..** </ul>.*/
4190: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
41a0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
41b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
41c0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
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 20 20 2f 2a 20 41 6e 20            /* An 
41f0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
4200: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
4210: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4230: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
4240: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
4250: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
4260: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
4270: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
4280: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
4290: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
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 20 20 2f 2a 20 31 73 74            /* 1st
42c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
42d0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
42e0: 2a 2a 65 72 72 6d 73 67 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 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
4310: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
4320: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
4330: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
4340: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4350: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
4360: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
4370: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
4380: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
4390: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
43a0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
43b0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
43c0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
43d0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
43e0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
43f0: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4400: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4410: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4420: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4430: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
4440: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4450: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
4460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4470: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
4480: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
4490: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
44a0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
44b0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
44c0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
44d0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
44e0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
44f0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4500: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4510: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4520: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
4530: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4550: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
4560: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
4570: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
4580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
4590: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
45a0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
45b0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
45c0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
45d0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
45e0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
45f0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4600: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4620: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
4630: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
4640: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
4650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4660: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
4670: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
4680: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
4690: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
46a0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
46b0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
46c0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
46d0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
46e0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
46f0: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4700: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4710: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4720: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
4730: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
4740: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
4750: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
4760: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
4770: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4780: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
4790: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
47a0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
47b0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
47c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
47d0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
47e0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
47f0: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
4800: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
4810: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4820: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4830: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4840: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4850: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4860: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4870: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
4880: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
4890: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
48a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48b0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
48c0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
48d0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
48e0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
48f0: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4900: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4910: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4930: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4940: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4950: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4970: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4980: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4990: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
49a0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49b0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49c0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49d0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49e0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
49f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a00: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a10: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a20: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a30: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a40: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a50: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a60: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a70: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a80: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4a90: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4aa0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4ab0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ac0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ad0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4ae0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b00: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b10: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4b20: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4b30: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4b40: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4b50: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4b60: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4b70: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4b80: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4b90: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4ba0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4bb0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4bc0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4bd0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4be0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
4bf0: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
4c00: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
4c10: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c20: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
4c30: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
4c40: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
4c50: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4c60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4c70: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4c80: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4c90: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4ca0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4cb0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cc0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4cd0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4ce0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4cf0: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d00: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d20: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d30: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4d40: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4d50: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4d60: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
4d70: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4d80: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4d90: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4da0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
4db0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
4dc0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4dd0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4de0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4df0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e00: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e10: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e20: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e30: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e40: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4e50: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4e60: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4e70: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4e80: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4e90: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4ea0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4eb0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4ec0: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4ed0: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4ee0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
4ef0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
4f00: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
4f10: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
4f20: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
4f30: 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65  ors. These [exte
4f40: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4f50: 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f  s] are enabled o
4f60: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e  r disabled.** on
4f70: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20   a per database 
4f80: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
4f90: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
4fa0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4fb0: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20  result_codes()] 
4fc0: 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78  API.  Or, the ex
4fd0: 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a  tended code for.
4fe0: 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
4ff0: 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20  nt error can be 
5000: 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a  obtained using.*
5010: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
5020: 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a  ded_errcode()]..
5030: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
5050: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
5090: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _UNLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  RDLOCK          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5270: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5280: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
5290: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
52a0: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
52b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
52c0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20  LOCKED          
52d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
52e0: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (11<<8)).#defin
52f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e  e SQLITE_IOERR_N
5300: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20  OMEM            
5310: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5320: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (12<<8)).#defin
5330: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41  e SQLITE_IOERR_A
5340: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20  CCESS           
5350: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5360: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (13<<8)).#defin
5370: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
5380: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b  HECKRESERVEDLOCK
5390: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53a0: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (14<<8)).#defin
53b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c  e SQLITE_IOERR_L
53c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
53d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53e0: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (15<<8)).#defin
53f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
5400: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20  LOSE            
5410: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5420: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (16<<8)).#defin
5430: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5440: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  IR_CLOSE        
5450: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5460: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (17<<8)).#defin
5470: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5480: 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20  HMOPEN          
5490: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
54a0: 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (18<<8)).#defin
54b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
54c0: 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  HMSIZE          
54d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
54e0: 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (19<<8)).#defin
54f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5500: 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  HMLOCK          
5510: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5520: 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (20<<8)).#defin
5530: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5540: 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  HMMAP           
5550: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5560: 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (21<<8)).#defin
5570: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5580: 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  EEK             
5590: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
55a0: 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (22<<8)).#defin
55b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
55c0: 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20  ELETE_NOENT     
55d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
55e0: 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (23<<8)).#defin
55f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d  e SQLITE_IOERR_M
5600: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20  MAP             
5610: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5620: 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (24<<8)).#defin
5630: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47  e SQLITE_IOERR_G
5640: 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20  ETTEMPPATH      
5650: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5660: 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (25<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
5680: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20  ONVPATH         
5690: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
56a0: 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (26<<8)).#defin
56b0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f  e SQLITE_LOCKED_
56c0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
56d0: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20   (SQLITE_LOCKED 
56e0: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
56f0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52  ne SQLITE_BUSY_R
5700: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20  ECOVERY         
5710: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
5720: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
5730: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
5740: 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20  SNAPSHOT        
5750: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
5760: 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65    |  (2<<8)).#de
5770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5780: 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20  OPEN_NOTEMPDIR  
5790: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
57a0: 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OPEN | (1<<8)).#
57b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
57c0: 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20  NTOPEN_ISDIR    
57d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57e0: 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29  NTOPEN | (2<<8))
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54  CANTOPEN_FULLPAT
5810: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5820: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38  CANTOPEN | (3<<8
5830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5840: 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50  E_CANTOPEN_CONVP
5850: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5860: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c  E_CANTOPEN | (4<
5870: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5880: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42  ITE_CORRUPT_VTAB
5890: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
58a0: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31  ITE_CORRUPT | (1
58b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45  LITE_READONLY_RE
58d0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51  COVERY       (SQ
58e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
58f0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5900: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5910: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28  CANTLOCK       (
5920: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5930: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5940: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5950: 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  Y_ROLLBACK      
5960: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5970: 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  Y | (3<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5990: 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20  NLY_DBMOVED     
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
59b0: 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  NLY | (4<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
59d0: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
59f0: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
5a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a10: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
5a20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a30: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
5a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a50: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
5a60: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
5a70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
5a80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5aa0: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
5ab0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ac0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5ad0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ae0: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
5af0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5b00: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
5b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b20: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
5b30: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5b40: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b60: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
5b70: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
5b80: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
5b90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ba0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
5bb0: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
5bc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bd0: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5be0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5bf0: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
5c00: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c10: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
5c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5c30: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
5c40: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5c50: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
5c60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c70: 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44  CONSTRAINT_ROWID
5c80: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5c90: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c  CONSTRAINT |(10<
5ca0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5cb0: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
5cc0: 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c  ER_WAL      (SQL
5cd0: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c  ITE_NOTICE | (1<
5ce0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5cf0: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56  ITE_NOTICE_RECOV
5d00: 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c  ER_ROLLBACK (SQL
5d10: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c  ITE_NOTICE | (2<
5d20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5d30: 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f  ITE_WARNING_AUTO
5d40: 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c  INDEX       (SQL
5d50: 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31  ITE_WARNING | (1
5d60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5d70: 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20  LITE_AUTH_USER  
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5d90: 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c  LITE_AUTH | (1<<
5da0: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
5db0: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
5dc0: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
5dd0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
5de0: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
5df0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
5e00: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
5e10: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e30: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
5e40: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
5e50: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5e60: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
5e70: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
5e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5e90: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
5ea0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
5eb0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5ec0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5ee0: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
5ef0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
5f00: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5f10: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5f30: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
5f40: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
5f50: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5f60: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5f80: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
5f90: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
5fa0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5fc0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
5fd0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
5fe0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6000: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
6010: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
6020: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6040: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6050: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6060: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6070: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6090: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
60a0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
60b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
60c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
60e0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
60f0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
6100: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6120: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
6130: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
6140: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6160: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6170: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
6180: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61a0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
61b0: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
61c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61e0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
61f0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
6200: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6220: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
6230: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
6240: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6260: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6270: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
6280: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62a0: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
62b0: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
62c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
62d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62f0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
6300: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6340: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6350: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6390: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
63a0: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
63b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
63c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
63d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63e0: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
63f0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
6400: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
6410: 2f 2a 20 52 65 73 65 72 76 65 64 3a 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 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
6440: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
6450: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
6460: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
6470: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6480: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
6490: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
64a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
64b0: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
64c0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
64d0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
64e0: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
64f0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
6500: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
6510: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
6520: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
6530: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
6540: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
6550: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6560: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
6570: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6580: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6590: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
65a0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
65b0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
65c0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
65d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
65e0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
65f0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6600: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6610: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
6620: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
6630: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
6640: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6650: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6660: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6670: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6680: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6690: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
66a0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
66b0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
66c0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
66d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
66e0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
66f0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6700: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6710: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
6720: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
6730: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6740: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6750: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6760: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6770: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6780: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6790: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
67a0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
67b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
67c0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
67d0: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
67e0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
67f0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
6800: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
6810: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
6820: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
6830: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
6840: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
6850: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
6860: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
6870: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
6880: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
6890: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
68a0: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
68b0: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
68c0: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
68d0: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ged.  The SQLITE
68e0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
68f0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20  LE_WHEN_OPEN.** 
6900: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68  flag indicate th
6910: 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74  at a file cannot
6920: 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e   be deleted when
6930: 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53   open.  The.** S
6940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6950: 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63  TABLE flag indic
6960: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69  ates that the fi
6970: 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64  le is on.** read
6980: 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20  -only media and 
6990: 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
69a0: 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73  d even by proces
69b0: 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76  ses with.** elev
69c0: 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e  ated privileges.
69d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
69e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6a00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
6a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6a20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
6a30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6a40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6a50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
6a60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
6a80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
6aa0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
6ab0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6ac0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ae0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
6af0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6b00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
6b10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
6b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
6b40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6b50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
6b60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6b70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
6b80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
6b90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6ba0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
6bb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
6bc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6bd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6be0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
6bf0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
6c00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6c10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
6c20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
6c30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6c50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
6c60: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
6c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6c80: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6c90: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
6ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6cb0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20  CAP_IMMUTABLE   
6cc0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6cd0: 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  02000../*.** CAP
6ce0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
6cf0: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
6d00: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
6d10: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
6d20: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6d30: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
6d40: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
6d50: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
6d60: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
6d70: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
6d80: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
6d90: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
6da0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6db0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
6dc0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
6dd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6de0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
6df0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
6e00: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
6e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6e20: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
6e30: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
6e40: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
6e50: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
6e60: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
6e70: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
6e80: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
6e90: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
6ea0: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
6eb0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
6ec0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6ed0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
6ee0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
6ef0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
6f00: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
6f10: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
6f20: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
6f30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6f40: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
6f50: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
6f60: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
6f70: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
6f80: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
6f90: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
6fa0: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
6fb0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
6fc0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
6fd0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6fe0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
6ff0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7000: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
7010: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
7020: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
7030: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
7040: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
7050: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7060: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
7070: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
7080: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7090: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
70a0: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
70b0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
70c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
70d0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
70e0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
70f0: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
7100: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7110: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7120: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7130: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7140: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
7150: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
7160: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
7170: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
7180: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
7190: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
71a0: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
71b0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
71c0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
71d0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
71e0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
71f0: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
7200: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7210: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7220: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7230: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7240: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
7250: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
7260: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
7270: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
7280: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
7290: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
72a0: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
72b0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
72c0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
72d0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
72e0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
72f0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
7300: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7310: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7320: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7330: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7340: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
7350: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
7360: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
7370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7380: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
7390: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
73a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
73b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
73c0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
73d0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
73e0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
73f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7400: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7410: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7420: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7430: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7440: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
7450: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
7460: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
7470: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
7480: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
7490: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
74a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
74b0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
74c0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
74d0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
74e0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
74f0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
7500: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7510: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7520: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7530: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7540: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
7550: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
7560: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
7570: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
7580: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
7590: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
75a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
75b0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
75c0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
75d0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
75e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
75f0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7600: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7610: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7620: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7630: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7640: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
7650: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
7660: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
7670: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
7680: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7690: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
76a0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
76b0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
76c0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
76d0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
76e0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
76f0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7700: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7710: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7720: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7730: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7740: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
7750: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
7760: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
7770: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
7780: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
7790: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
77a0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
77b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
77c0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
77d0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
77e0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
77f0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7800: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7810: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7820: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7830: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7840: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
7850: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
7860: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
7870: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
7880: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
7890: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
78a0: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
78b0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
78c0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
78d0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
78e0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
78f0: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7900: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7910: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7920: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7930: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7940: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7950: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7960: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7970: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7980: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
7990: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
79a0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
79b0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
79c0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
79d0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
79e0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
79f0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7a00: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7a10: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7a20: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7a30: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7a40: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7a50: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7a60: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7a70: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7a80: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
7a90: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
7aa0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7ab0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
7ac0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
7ad0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
7ae0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
7af0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7b00: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7b10: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
7b20: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7b30: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
7b40: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
7b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
7b60: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
7b70: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
7b80: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
7b90: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
7ba0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
7bb0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
7bc0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
7bd0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
7be0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
7bf0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
7c00: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
7c10: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
7c20: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
7c30: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
7c40: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
7c50: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
7c60: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
7c70: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
7c80: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
7c90: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
7ca0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
7cb0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
7cc0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
7cd0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
7ce0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
7cf0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
7d00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
7d10: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
7d20: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
7d30: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
7d40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
7d50: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
7d60: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
7d70: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
7d80: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
7d90: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
7da0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
7db0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
7dc0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
7dd0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
7de0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
7df0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
7e00: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
7e10: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
7e20: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
7e30: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
7e40: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
7e50: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
7e60: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
7e70: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
7e80: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
7e90: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
7ea0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
7eb0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
7ec0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
7ed0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
7ee0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
7ef0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
7f00: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
7f10: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
7f20: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
7f30: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
7f40: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
7f50: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
7f60: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
7f70: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
7f80: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
7f90: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
7fa0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
7fb0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
7fc0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
7fd0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
7fe0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
7ff0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
8000: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
8010: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
8020: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8030: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
8040: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
8050: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
8060: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
8070: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
8080: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
8090: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
80a0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
80b0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
80c0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
80d0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
80e0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
80f0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
8100: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
8110: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
8120: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
8130: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
8140: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
8150: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
8160: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8170: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
8180: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
8190: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
81a0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
81b0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
81c0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
81d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
81e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
81f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8200: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8210: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8220: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8230: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8240: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8250: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8260: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8270: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8280: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
8290: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
82b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
82d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
82e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
82f0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8300: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8310: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8320: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8330: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
8340: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8350: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8360: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8370: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8380: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
8390: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
83a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83b0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
83c0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
83d0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
83e0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
83f0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8400: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8410: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8420: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8430: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8440: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8460: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8470: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8480: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
8490: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
84a0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
84b0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
84c0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
84d0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
84e0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
84f0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8500: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8510: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8520: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8530: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8540: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8550: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8560: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8570: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8580: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
8590: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
85a0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
85b0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
85c0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
85d0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
85e0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
85f0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8600: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8610: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8620: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8630: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8640: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8650: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8660: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8670: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8680: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
8690: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
86a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
86b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
86c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
86d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
86e0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
86f0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8700: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8710: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8720: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8730: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8740: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8750: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8760: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8780: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
8790: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
87a0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
87b0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
87c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
87d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
87e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
87f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8800: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8810: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8820: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8830: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8840: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8850: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8860: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8870: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8880: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
8890: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
88a0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
88b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
88c0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
88d0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
88e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
88f0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8900: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8910: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8920: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8930: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8940: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8950: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8960: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8970: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8980: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
8990: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
89a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
89b0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
89c0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
89d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
89e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
89f0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8a00: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8a10: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
8a20: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
8a30: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8a40: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
8a50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
8a60: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
8a70: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8a80: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8a90: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
8aa0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
8ab0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8ac0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
8ad0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
8ae0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
8af0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8b00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8b10: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
8b20: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8b30: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8b40: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
8b50: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
8b60: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
8b70: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
8b80: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
8b90: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
8ba0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
8bb0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
8bc0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
8bd0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
8be0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8bf0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
8c00: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
8c10: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
8c20: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
8c30: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
8c40: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
8c50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
8c60: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
8c70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8c80: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
8c90: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
8ca0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8cb0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8cc0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8cd0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8ce0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8cf0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8d00: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8d10: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8d20: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8d30: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8d40: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8d50: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8d60: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8d70: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8d80: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8d90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8da0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8db0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8dc0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8dd0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8de0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8df0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
8e00: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
8e10: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
8e20: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
8e30: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
8e40: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
8e50: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
8e60: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
8e70: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
8e80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
8e90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8ea0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
8eb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8ec0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8ed0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8ee0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8ef0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8f00: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8f10: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8f20: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8f30: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
8f40: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
8f50: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
8f60: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
8f70: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
8f80: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
8f90: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8fa0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
8fb0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
8fc0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8fd0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8fe0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8ff0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
9000: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
9010: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
9020: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
9030: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9040: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
9050: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
9060: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9070: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
9080: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
9090: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
90a0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
90b0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
90c0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
90d0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
90e0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
90f0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
9100: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
9110: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9120: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9130: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
9140: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
9150: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9160: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9170: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
9180: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
9190: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
91a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
91b0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
91c0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
91d0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
91e0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
91f0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9200: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
9210: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9220: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9230: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9240: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
9250: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9260: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9270: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9280: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9290: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
92a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
92b0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
92c0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
92d0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
92e0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
92f0: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
9300: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9310: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
9320: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
9330: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
9340: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9350: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9360: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9370: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9380: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9390: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
93a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
93b0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
93c0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
93d0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
93e0: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
93f0: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9400: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
9410: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
9420: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
9430: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
9440: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
9450: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9460: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9470: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9480: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9490: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
94a0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
94b0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
94c0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
94d0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
94e0: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
94f0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9500: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
9510: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
9520: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
9530: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
9540: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
9550: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
9560: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9570: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9580: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9590: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
95a0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
95b0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
95c0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
95d0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
95e0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
95f0: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
9600: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
9610: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
9620: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9630: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
9640: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9650: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
9660: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
9670: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
9680: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9690: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
96a0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
96b0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
96c0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
96d0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
96e0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
96f0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9700: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9710: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9720: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
9730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9740: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
9750: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
9760: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
9770: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
9780: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
9790: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
97a0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
97b0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
97c0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
97d0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
97e0: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
97f0: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
9800: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
9810: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9820: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9830: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
9840: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
9850: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9860: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9870: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9880: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
9890: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
98a0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
98b0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
98c0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
98d0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
98e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
98f0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
9900: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9910: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9920: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
9930: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
9940: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
9950: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
9960: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
9970: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
9980: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
9990: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
99a0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
99b0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
99c0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
99d0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
99e0: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
99f0: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
9a00: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
9a10: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
9a20: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
9a30: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
9a40: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
9a50: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
9a60: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
9a70: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
9a80: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
9a90: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
9aa0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
9ab0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
9ac0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
9ad0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
9ae0: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
9af0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
9b00: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
9b10: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
9b20: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
9b30: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
9b40: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
9b50: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
9b60: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
9b70: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
9b80: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
9b90: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
9ba0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
9bb0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
9bc0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
9bd0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
9be0: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
9bf0: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65  integer i the ne
9c00: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
9c10: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
9c20: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
9c30: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
9c40: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
9c50: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
9c60: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
9c70: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
9c80: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
9c90: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
9ca0: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
9cb0: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
9cc0: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
9cd0: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
9ce0: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
9cf0: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
9d00: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
9d10: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
9d20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
9d30: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9d40: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
9d50: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9d60: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9d70: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9d80: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
9d90: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
9da0: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
9db0: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
9dc0: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
9dd0: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
9de0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
9df0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
9e00: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
9e10: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
9e20: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
9e30: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
9e40: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
9e50: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
9e60: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9e70: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
9e80: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
9e90: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
9ea0: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
9eb0: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
9ec0: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
9ed0: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
9ee0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
9ef0: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
9f00: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
9f10: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
9f20: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
9f30: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
9f40: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
9f50: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
9f60: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
9f70: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
9f80: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9f90: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
9fa0: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
9fb0: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
9fc0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
9fd0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9fe0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
9ff0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a000: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a010: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a020: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a030: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a040: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a050: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
a060: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a070: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
a080: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
a090: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
a0a0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
a0b0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
a0c0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
a0d0: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
a0e0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a0f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a100: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a110: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a120: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a130: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a140: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a150: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a160: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a170: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
a180: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
a190: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
a1a0: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
a1b0: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
a1c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
a1d0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a1e0: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
a1f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
a200: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
a210: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
a220: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
a230: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a240: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
a250: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
a260: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a270: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a280: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a290: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
a2a0: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
a2b0: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
a2c0: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
a2d0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
a2e0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
a2f0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
a300: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
a310: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a320: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a330: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a340: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
a350: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a360: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
a370: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
a380: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
a390: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
a3a0: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
a3b0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
a3c0: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
a3d0: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
a3e0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
a3f0: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
a400: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
a410: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
a420: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
a430: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
a440: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
a450: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
a460: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a470: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a480: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a490: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a4a0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
a4b0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
a4c0: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
a4d0: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
a4e0: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
a4f0: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
a500: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
a510: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
a520: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
a530: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
a540: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
a550: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
a560: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
a570: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
a580: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
a590: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
a5a0: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
a5b0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
a5c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a5d0: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
a5e0: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
a5f0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
a600: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
a610: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
a620: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
a630: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
a640: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
a650: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
a660: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
a670: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
a680: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
a690: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
a6a0: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
a6b0: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
a6c0: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
a6d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
a6e0: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
a6f0: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
a700: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
a710: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
a720: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
a730: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a740: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
a750: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
a760: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
a770: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
a780: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a790: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
a7a0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
a7b0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
a7c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
a7d0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
a7e0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
a7f0: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
a800: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
a810: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
a820: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
a830: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a840: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a850: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
a860: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
a870: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
a880: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
a890: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
a8a0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
a8b0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
a8c0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
a8d0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
a8e0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a8f0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
a900: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
a910: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
a920: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
a930: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
a940: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
a950: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a960: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
a970: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
a980: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
a990: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
a9a0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
a9b0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
a9c0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
a9d0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
a9e0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
a9f0: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
aa00: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
aa10: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
aa20: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
aa30: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
aa40: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
aa50: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
aa60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aa70: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
aa80: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
aa90: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
aaa0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
aab0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
aac0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
aad0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aae0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
aaf0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
ab00: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
ab10: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
ab20: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
ab30: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
ab40: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
ab50: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
ab60: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
ab70: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
ab80: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
ab90: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
aba0: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
abb0: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
abc0: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
abd0: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
abe0: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
abf0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
ac00: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
ac10: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ac20: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
ac30: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
ac40: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
ac50: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
ac60: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
ac70: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
ac80: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
ac90: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
aca0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
acb0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
acc0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
acd0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
ace0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
acf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ad00: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
ad10: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
ad20: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
ad30: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
ad40: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
ad50: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
ad60: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
ad70: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
ad80: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
ad90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ada0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
adb0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
adc0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
add0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
ade0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
adf0: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
ae00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ae10: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
ae20: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
ae30: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
ae40: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
ae50: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
ae60: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
ae70: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
ae80: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
ae90: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
aea0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
aeb0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
aec0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
aed0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
aee0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
aef0: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
af00: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
af10: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
af20: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
af30: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
af40: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
af50: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
af60: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
af70: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
af80: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
af90: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
afa0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
afb0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
afc0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
afd0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
afe0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
aff0: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
b000: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
b010: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
b020: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
b030: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
b040: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b050: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b060: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
b070: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
b080: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
b090: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b0a0: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
b0b0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
b0c0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
b0d0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
b0e0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
b0f0: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
b100: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
b110: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
b120: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b130: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
b140: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
b150: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
b160: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
b170: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
b180: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
b190: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
b1a0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
b1b0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
b1c0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
b1d0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b1e0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
b1f0: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
b200: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
b210: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
b220: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
b230: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
b240: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b250: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
b260: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b270: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
b280: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b290: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
b2a0: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
b2b0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b2c0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
b2d0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
b2e0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
b2f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
b300: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
b310: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
b320: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
b330: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
b340: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b350: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
b360: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
b370: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
b380: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
b390: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
b3a0: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
b3b0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
b3c0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
b3d0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
b3e0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
b3f0: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
b400: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
b410: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
b420: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
b430: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
b440: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
b450: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
b460: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
b470: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
b480: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
b490: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
b4a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b4b0: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
b4c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b4d0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b4e0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
b4f0: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
b500: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
b510: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
b520: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
b530: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
b540: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
b550: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b560: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
b570: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
b580: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
b590: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b5a0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
b5b0: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
b5c0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
b5d0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
b5e0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
b5f0: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
b600: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
b610: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
b620: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
b630: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
b640: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
b650: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b660: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b670: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b680: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b690: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b6a0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
b6b0: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
b6c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
b6d0: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
b6e0: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
b6f0: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
b700: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
b710: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
b720: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
b730: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
b740: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
b750: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
b760: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
b770: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b780: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b790: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
b7a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b7b0: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
b7c0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
b7d0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
b7e0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
b7f0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
b800: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
b810: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
b820: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
b830: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
b840: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
b850: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
b860: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
b870: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
b880: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
b890: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
b8a0: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
b8b0: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
b8c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b8d0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
b8e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b8f0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
b900: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
b910: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
b920: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
b930: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
b940: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
b950: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
b960: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
b970: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
b980: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
b990: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
b9a0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
b9b0: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
b9c0: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
b9d0: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
b9e0: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
b9f0: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
ba00: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
ba10: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
ba20: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
ba30: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 2f  ontrol..**.** </
ba40: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
ba50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
ba60: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
ba70: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
ba80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
ba90: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
baa0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
bab0: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
bac0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
bad0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
bae0: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
baf0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
bb00: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
bb10: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
bb20: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
bb30: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
bb40: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
bb50: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
bb60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bb70: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
bb80: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
bb90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bba0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
bbb0: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
bbc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bbd0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
bbe0: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
bbf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc00: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
bc10: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
bc20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc30: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
bc40: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
bc50: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bc60: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
bc70: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
bc80: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bc90: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
bca0: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
bcb0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
bcc0: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
bcd0: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
bce0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
bcf0: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
bd00: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
bd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
bd20: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
bd30: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
bd40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
bd50: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
bd60: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
bd70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
bd80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bd90: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
bda0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bdb0: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
bdc0: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
bdd0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
bde0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bdf0: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
be00: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
be10: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
be20: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
be30: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
be40: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33  _HANDLE       23
be50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
be60: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20  FCNTL_WAL_BLOCK 
be70: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a               24.
be80: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
be90: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
bea0: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
beb0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bec0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
bed0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
bee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
bef0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bf00: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
bf10: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
bf20: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
bf30: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
bf40: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
bf50: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
bf60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
bf70: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
bf80: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
bf90: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
bfa0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
bfb0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
bfc0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
bfd0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
bfe0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
bff0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c000: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c010: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c020: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c030: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c040: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c050: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c060: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c070: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c080: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c090: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c0a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c0b0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c0c0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c0d0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c0e0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c0f0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c100: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
c110: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
c120: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c130: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c140: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c150: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
c160: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
c170: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
c180: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
c190: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
c1a0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
c1b0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
c1c0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
c1d0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
c1e0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
c1f0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
c200: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
c210: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
c220: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
c230: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
c240: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
c250: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
c260: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
c270: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
c280: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
c290: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
c2a0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
c2b0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
c2c0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
c2d0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
c2e0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
c2f0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
c300: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c310: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
c320: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
c330: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
c340: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
c350: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
c360: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c370: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
c380: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
c390: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
c3a0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c3b0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
c3c0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
c3d0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
c3e0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
c3f0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
c400: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
c410: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
c420: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
c430: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
c440: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
c450: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
c460: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
c470: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
c480: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
c490: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
c4a0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
c4b0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
c4c0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
c4d0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
c4e0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
c4f0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
c500: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c510: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
c520: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
c530: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
c540: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c550: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
c560: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
c570: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
c580: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c590: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
c5a0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
c5b0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
c5c0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c5d0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
c5e0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
c5f0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
c600: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
c610: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
c620: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
c630: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
c640: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
c650: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c660: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c670: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
c680: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
c690: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
c6a0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
c6b0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
c6c0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
c6d0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
c6e0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
c6f0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
c700: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
c710: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
c720: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
c730: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
c740: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
c750: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
c760: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
c770: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c780: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
c790: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
c7a0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
c7b0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
c7c0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
c7d0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
c7e0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
c7f0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
c800: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
c810: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c820: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
c830: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
c840: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
c850: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
c860: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
c870: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
c880: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
c890: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
c8a0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
c8b0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
c8c0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
c8d0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
c8e0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
c8f0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
c900: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
c910: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
c920: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
c930: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
c940: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
c950: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
c960: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
c970: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
c980: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
c990: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
c9a0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
c9b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
c9c0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
c9d0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
c9e0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
c9f0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
ca00: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
ca10: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
ca20: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
ca30: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
ca40: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
ca50: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
ca60: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
ca70: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
ca80: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
ca90: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
caa0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
cab0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
cac0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
cad0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
cae0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
caf0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
cb00: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
cb10: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
cb20: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
cb30: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
cb40: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
cb50: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
cb60: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
cb70: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
cb80: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
cb90: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
cba0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
cbb0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
cbc0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
cbd0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
cbe0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cbf0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
cc00: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
cc10: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
cc20: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
cc30: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
cc40: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cc50: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
cc60: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
cc70: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
cc80: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
cc90: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
cca0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
ccb0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
ccc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ccd0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
cce0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ccf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
cd00: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
cd10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
cd20: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
cd30: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
cd40: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
cd50: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cd60: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
cd70: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cd80: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
cd90: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
cda0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
cdb0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
cdc0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
cdd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
cde0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
cdf0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
ce00: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
ce10: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
ce20: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
ce30: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
ce40: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
ce50: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
ce60: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
ce70: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
ce80: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
ce90: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
cea0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
ceb0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
cec0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
ced0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
cee0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
cef0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
cf00: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
cf10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
cf20: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
cf30: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
cf40: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
cf50: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
cf60: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
cf70: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
cf80: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
cf90: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
cfa0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
cfb0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
cfc0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
cfd0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
cfe0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
cff0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d000: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d010: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d020: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d040: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d050: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d060: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d070: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d080: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d090: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d0a0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d0b0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d0c0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d0d0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d0e0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d0f0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d100: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
d110: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
d120: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
d130: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
d140: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
d150: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
d160: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
d170: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
d180: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
d190: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
d1a0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
d1b0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
d1c0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
d1d0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
d1e0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
d1f0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
d200: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
d210: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
d220: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
d230: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
d240: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
d250: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
d260: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d270: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
d280: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
d290: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
d2a0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
d2b0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
d2c0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
d2d0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
d2e0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
d2f0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d300: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
d310: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
d320: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
d330: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
d340: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
d350: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
d360: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
d370: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
d380: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
d390: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
d3a0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
d3b0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
d3c0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
d3d0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
d3e0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
d3f0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
d400: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
d410: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
d420: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
d430: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d440: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
d450: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d460: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
d470: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
d480: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d490: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
d4a0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
d4b0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
d4c0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
d4d0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
d4e0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
d4f0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
d500: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
d510: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
d520: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
d530: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
d540: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
d550: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
d560: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
d570: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
d580: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
d590: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
d5a0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
d5b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d5c0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
d5d0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
d5e0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
d5f0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d600: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
d610: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d620: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
d630: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
d640: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d650: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
d660: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d670: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
d680: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
d690: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
d6a0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
d6b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
d6c0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
d6d0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
d6e0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
d6f0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
d700: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
d710: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
d720: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
d730: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
d740: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
d750: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
d760: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
d770: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d780: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
d790: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
d7a0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
d7b0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
d7c0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
d7d0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
d7e0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
d7f0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
d800: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
d810: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
d820: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
d830: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
d840: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
d850: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
d860: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d870: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
d880: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
d890: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
d8a0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
d8b0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
d8c0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
d8d0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
d8e0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
d8f0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
d900: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
d910: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
d920: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
d930: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
d940: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
d950: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
d960: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
d970: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
d980: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
d990: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
d9a0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
d9b0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
d9c0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
d9d0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
d9e0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
d9f0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
da00: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
da10: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
da20: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
da30: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
da40: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
da50: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
da60: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
da70: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
da80: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
da90: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
daa0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
dab0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
dac0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dad0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
dae0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
daf0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
db00: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
db10: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
db20: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
db30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
db40: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
db50: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
db60: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
db70: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
db80: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
db90: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
dba0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
dbb0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
dbc0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
dbd0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
dbe0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
dbf0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
dc00: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
dc10: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
dc20: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
dc30: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
dc40: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
dc50: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
dc60: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
dc70: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
dc80: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
dc90: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
dca0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
dcb0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
dcc0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
dcd0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
dce0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
dcf0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
dd00: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
dd10: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
dd20: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
dd30: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
dd40: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
dd50: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
dd60: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
dd70: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
dd80: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
dd90: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
dda0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
ddb0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
ddc0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
ddd0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
dde0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
ddf0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
de00: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
de10: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
de20: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
de30: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
de40: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
de50: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
de60: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
de70: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
de80: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
de90: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
dea0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
deb0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
dec0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
ded0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
dee0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
def0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
df00: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
df10: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
df20: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
df30: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
df40: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
df50: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
df60: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
df70: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
df80: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
df90: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
dfa0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
dfb0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
dfc0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
dfd0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
dfe0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
dff0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e000: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e010: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e020: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e030: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e040: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e050: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e060: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e070: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e080: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e090: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e0a0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e0b0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e0c0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e0d0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e0e0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e0f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e100: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
e110: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
e120: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e130: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
e140: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
e150: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
e160: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
e170: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
e180: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
e190: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e1a0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e1b0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
e1c0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
e1d0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
e1e0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
e1f0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
e200: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e210: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
e220: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
e230: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
e240: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e250: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
e260: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
e270: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
e280: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
e290: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e2a0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
e2b0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e2c0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
e2d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e2e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
e2f0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
e300: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
e310: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e320: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
e330: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
e340: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
e350: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
e360: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
e370: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
e380: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
e390: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
e3a0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
e3b0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
e3c0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
e3d0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
e3e0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
e3f0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
e400: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
e410: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e420: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e430: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
e440: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
e450: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e460: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
e470: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e480: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e490: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
e4a0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e4b0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
e4c0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
e4d0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
e4e0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
e4f0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
e500: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e510: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
e520: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
e530: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
e540: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e550: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e560: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
e570: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e580: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
e590: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
e5a0: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
e5b0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
e5c0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
e5d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e5e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e5f0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
e600: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
e610: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
e620: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
e630: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e640: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e650: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
e660: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
e670: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e680: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e690: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
e6a0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e6b0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e6c0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
e6d0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e6e0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
e6f0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
e700: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
e710: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
e720: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
e730: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
e740: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
e750: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
e760: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
e770: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e780: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
e790: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
e7a0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
e7b0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
e7c0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
e7d0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
e7e0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e7f0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
e800: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
e810: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
e820: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
e830: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
e840: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
e850: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
e860: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e870: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
e880: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
e890: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
e8a0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
e8b0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
e8c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e8d0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
e8e0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
e8f0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
e900: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
e910: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
e920: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
e930: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
e940: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
e950: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
e960: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
e970: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
e980: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
e990: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e9a0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
e9b0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
e9c0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
e9d0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
e9e0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
e9f0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
ea00: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
ea10: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
ea20: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
ea30: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
ea40: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
ea50: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
ea60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
ea70: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
ea80: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
ea90: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
eaa0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
eab0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
eac0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
ead0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
eae0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
eaf0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
eb00: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
eb10: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
eb20: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
eb30: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
eb40: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
eb50: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
eb60: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
eb70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
eb80: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
eb90: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
eba0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
ebb0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
ebc0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
ebd0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
ebe0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
ebf0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
ec00: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
ec10: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
ec20: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ec30: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
ec40: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
ec50: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
ec60: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
ec70: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
ec80: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
ec90: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
eca0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ecb0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
ecc0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
ecd0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
ece0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
ecf0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
ed00: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
ed10: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ed20: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ed30: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
ed40: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ed50: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ed60: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
ed70: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
ed80: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
ed90: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
eda0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
edb0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
edc0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
edd0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
ede0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
edf0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ee00: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
ee10: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
ee20: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
ee30: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
ee40: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
ee50: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
ee60: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
ee70: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
ee80: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
ee90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
eea0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
eeb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
eec0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
eed0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
eee0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
eef0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
ef00: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ef10: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
ef20: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
ef30: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
ef40: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
ef50: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
ef60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
ef70: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
ef80: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
ef90: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
efa0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
efb0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
efc0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
efd0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
efe0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
eff0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f000: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f010: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f020: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f030: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f040: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f050: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f060: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f070: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f080: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f090: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f0a0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f0b0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f0c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f0d0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f0e0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f0f0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f100: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
f110: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f120: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
f130: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
f140: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
f150: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
f160: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
f170: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
f180: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
f190: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
f1a0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
f1b0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
f1c0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
f1d0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
f1e0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f1f0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f200: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f210: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f220: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
f230: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
f240: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f250: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f260: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
f270: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
f280: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
f290: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
f2a0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
f2b0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
f2c0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
f2d0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
f2e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
f2f0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
f300: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
f310: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f320: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
f330: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
f340: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
f350: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
f360: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
f370: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f380: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
f390: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
f3a0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f3b0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
f3c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f3d0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
f3e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f3f0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
f400: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
f410: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f420: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
f430: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
f440: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
f450: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
f460: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f470: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
f480: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
f490: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
f4a0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
f4b0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
f4c0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
f4d0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
f4e0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
f4f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
f500: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
f510: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
f520: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
f530: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
f540: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f550: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
f560: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
f570: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
f580: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
f590: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
f5a0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
f5b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f5c0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
f5d0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
f5e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f5f0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
f600: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f610: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
f620: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
f630: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
f640: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
f650: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
f660: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f670: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
f680: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f690: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
f6a0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
f6b0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
f6c0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
f6d0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
f6e0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
f6f0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
f700: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
f710: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
f720: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
f730: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
f740: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
f750: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
f760: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
f770: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f780: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f790: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
f7a0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
f7b0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
f7c0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
f7d0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
f7e0: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
f7f0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
f800: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f810: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f820: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
f830: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
f840: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
f850: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f860: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
f870: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
f880: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
f890: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
f8a0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
f8b0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
f8c0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
f8d0: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
f8e0: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
f8f0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
f900: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
f910: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
f920: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
f930: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
f940: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
f950: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
f960: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f970: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
f980: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
f990: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
f9a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f9b0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
f9c0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
f9d0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
f9e0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
f9f0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
fa00: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
fa10: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
fa20: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
fa30: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
fa40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
fa50: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
fa60: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
fa70: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fa80: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
fa90: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
faa0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
fab0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
fac0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
fad0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
fae0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
faf0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
fb00: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
fb10: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
fb20: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
fb30: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
fb40: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
fb50: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
fb60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fb70: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
fb80: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
fb90: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
fba0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fbb0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
fbc0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
fbd0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fbe0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
fbf0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
fc00: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
fc10: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
fc20: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
fc30: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
fc40: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
fc50: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
fc60: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
fc70: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
fc80: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
fc90: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
fca0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
fcb0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
fcc0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
fcd0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
fce0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
fcf0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
fd00: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
fd10: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
fd20: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
fd30: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
fd40: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fd50: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
fd60: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
fd70: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
fd80: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
fd90: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
fda0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
fdb0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
fdc0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
fdd0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
fde0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
fdf0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
fe00: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
fe10: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
fe20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fe30: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
fe40: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fe50: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
fe60: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
fe70: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
fe80: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
fe90: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
fea0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
feb0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
fec0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
fed0: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
fee0: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
fef0: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
ff00: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
ff10: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
ff20: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
ff30: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
ff40: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
ff50: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
ff60: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
ff70: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
ff80: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
ff90: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
ffa0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
ffb0: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
ffc0: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
ffd0: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
ffe0: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
fff0: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
10000 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10010 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10020 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10030 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10040 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10050 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10060 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
10070 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
10080 4c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  L sqlite3_initia
10090 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
100a0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
100b0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
100c0 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
100d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
100e0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
100f0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10100 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
10110 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
10120 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f  CALL sqlite3_os_
10130 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
10140 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
10150 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
10160 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
10170 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
10180 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
10190 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
101a0 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
101b0 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
101c0 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
101d0 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
101e0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
101f0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
10200 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
10210 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
10220 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
10230 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
10240 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
10250 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
10260 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
10270 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
10280 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
10290 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
102a0 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
102b0 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
102c0 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
102d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
102e0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
102f0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
10300 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
10310 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
10320 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
10330 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10340 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
10350 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
10360 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10370 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
10380 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
10390 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
103a0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
103b0 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
103c0 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
103d0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
103e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
103f0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
10400 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
10410 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
10420 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
10430 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
10440 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
10450 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
10460 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
10470 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10480 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
10490 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
104a0 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
104b0 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
104c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
104d0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
104e0 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
104f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
10500 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
10510 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
10520 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
10530 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
10540 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
10550 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
10560 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
10570 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
10580 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
10590 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
105a0 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
105b0 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
105c0 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
105d0 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
105e0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
105f0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
10600 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
10610 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
10620 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
10630 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10640 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
10650 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
10660 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
10670 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
10680 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
10690 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
106a0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
106b0 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
106c0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
106d0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
106e0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51  ror code]..*/.SQ
106f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
10700 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65  ITE_CDECL sqlite
10710 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
10720 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
10730 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
10740 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10750 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
10760 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
10770 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10780 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10790 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
107a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
107b0 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
107c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
107d0 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
107e0 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
107f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10800 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
10810 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
10820 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
10830 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
10840 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
10850 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
10860 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
10870 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
10880 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10890 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
108a0 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
108b0 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
108c0 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
108d0 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
108e0 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
108f0 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
10900 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
10910 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
10920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
10930 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
10940 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
10950 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
10960 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
10970 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
10980 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
10990 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
109a0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
109b0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
109c0 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
109d0 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
109e0 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
109f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
10a00 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73  t SQLITE_CDECL s
10a10 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10a20 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
10a30 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
10a40 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
10a50 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
10a60 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
10a70 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10a80 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
10a90 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
10aa0 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
10ab0 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
10ac0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
10ad0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
10ae0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
10af0 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
10b00 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
10b10 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
10b20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
10b30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10b40 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
10b50 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
10b60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10b70 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
10b80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
10b90 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
10ba0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
10bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10bc0 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
10bd0 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
10be0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10bf0 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
10c00 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
10c10 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
10c20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10c30 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
10c40 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
10c50 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
10c60 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
10c70 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
10c80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
10c90 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
10ca0 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
10cb0 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
10cc0 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
10cd0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
10ce0 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
10cf0 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
10d00 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
10d10 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
10d20 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
10d30 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
10d40 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
10d50 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
10d60 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
10d70 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
10d80 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
10d90 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
10da0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
10db0 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
10dc0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
10dd0 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
10de0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
10df0 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
10e00 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
10e10 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
10e20 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
10e30 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
10e40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
10e50 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
10e60 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
10e70 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
10e80 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
10e90 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
10ea0 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
10eb0 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
10ec0 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
10ed0 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
10ee0 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
10ef0 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
10f00 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
10f10 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
10f20 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
10f30 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
10f40 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
10f50 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
10f60 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
10f70 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
10f80 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
10f90 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
10fa0 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
10fb0 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
10fc0 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
10fd0 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
10fe0 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
10ff0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
11000 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11010 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
11020 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
11030 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
11040 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
11050 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
11060 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
11070 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
11080 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
11090 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
110a0 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
110b0 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
110c0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
110d0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
110e0 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
110f0 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
11100 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
11110 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
11120 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
11130 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
11140 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11150 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
11160 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
11170 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
11180 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
11190 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
111a0 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
111b0 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
111c0 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
111d0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
111e0 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
111f0 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
11200 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
11210 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
11220 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
11230 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
11240 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
11250 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
11260 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
11270 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11280 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
11290 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
112a0 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
112b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
112c0 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  or.  For example
112d0 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
112e0 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
112f0 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
11300 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
11310 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
11320 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
11330 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
11340 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
11350 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
11360 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
11370 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
11380 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
11390 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
113a0 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
113b0 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
113c0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
113d0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
113e0 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
113f0 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
11400 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
11410 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
11420 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
11430 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
11440 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
11450 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
11460 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
11470 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
11480 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
11490 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
114a0 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
114b0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
114c0 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
114d0 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
114e0 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
114f0 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
11500 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
11510 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
11520 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
11530 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
11540 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
11550 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
11560 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
11570 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11580 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
11590 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
115a0 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
115b0 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
115c0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
115d0 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
115e0 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
115f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
11600 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
11610 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
11620 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
11630 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
11640 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
11650 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
11660 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
11670 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
11680 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
11690 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
116a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
116b0 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
116c0 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
116d0 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
116e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
116f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11700 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
11710 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
11720 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11730 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
11740 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
11750 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
11760 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
11770 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
11780 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
11790 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
117a0 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
117b0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
117c0 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
117d0 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
117e0 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
117f0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
11800 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
11810 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
11820 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
11830 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
11840 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
11850 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
11860 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
11870 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
11880 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
11890 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
118a0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
118b0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
118c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
118d0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
118e0 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
118f0 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
11900 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
11910 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
11920 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
11930 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
11940 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
11950 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
11960 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
11970 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
11980 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
11990 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
119a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
119b0 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on}.**.** These 
119c0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
119d0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
119e0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
119f0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
11a00 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
11a10 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
11a20 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
11a30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11a40 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
11a50 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
11a60 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
11a70 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
11a80 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
11a90 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
11aa0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
11ab0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
11ac0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
11ad0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
11ae0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
11af0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
11b00 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
11b10 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
11b20 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
11b30 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
11b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11b50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
11b60 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
11b70 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
11b80 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
11b90 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
11ba0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
11bb0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
11bc0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
11bd0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
11be0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
11bf0 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
11c00 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
11c10 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
11c20 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
11c30 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
11c40 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
11c50 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
11c60 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
11c70 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
11c80 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
11c90 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
11ca0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
11cb0 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
11cc0 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
11cd0 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
11ce0 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
11cf0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
11d00 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11d10 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11d20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11d30 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11d40 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11d50 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11d60 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11d70 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11d80 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
11d90 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
11da0 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
11db0 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
11dc0 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
11dd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11de0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
11df0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
11e00 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
11e10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11e20 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
11e30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11e40 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11e50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11e60 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20  G_MULTITHREAD]] 
11e70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11e80 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
11e90 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
11ea0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11eb0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11ec0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11ed0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
11ee0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
11ef0 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e  ulti-thread.  In
11f00 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
11f10 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
11f20 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
11f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11f40 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11f50 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
11f60 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
11f70 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
11f80 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
11f90 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
11fa0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11fb0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
11fc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
11fd0 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
11fe0 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
11ff0 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
12000 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
12010 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
12020 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
12030 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
12040 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
12050 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
12060 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
12070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12080 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
12090 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69   time.  ^If SQLi
120a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
120b0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
120c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
120d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
120e0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
120f0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12100 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
12110 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d  ble to set the M
12120 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
12130 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
12140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12150 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
12160 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12170 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
12180 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
12190 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
121a0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
121b0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
121c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
121d0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20  IG_SERIALIZED]] 
121e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
121f0 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
12200 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
12210 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
12220 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
12230 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
12240 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
12250 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
12260 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
12270 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
12280 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
12290 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
122a0 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
122b0 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
122c0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
122d0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
122e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
122f0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
12300 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
12310 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
12320 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
12330 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12340 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12350 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
12360 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
12370 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
12380 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
12390 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
123a0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
123b0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
123c0 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
123d0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
123e0 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
123f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
12400 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
12410 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
12420 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
12430 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
12440 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
12450 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
12460 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12470 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12480 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12490 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
124a0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
124b0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
124c0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
124d0 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
124e0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
124f0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
12500 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12510 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
12520 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
12530 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
12540 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
12550 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
12560 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12570 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12580 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12590 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
125a0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
125b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
125c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
125d0 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  _MALLOC option t
125e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
125f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12600 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
12610 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
12620 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
12630 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12640 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
12650 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
12660 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
12670 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
12680 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12690 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
126a0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
126b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
126c0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
126d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
126e0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
126f0 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
12700 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
12710 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
12720 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12730 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
12740 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
12750 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
12760 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
12770 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12780 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12790 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
127a0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
127b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
127c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
127d0 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  GETMALLOC option
127e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
127f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
12800 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
12810 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12820 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12830 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12840 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  ture..** The [sq
12850 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12860 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
12870 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
12880 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
12890 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
128a0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
128b0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
128c0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
128d0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
128e0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
128f0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
12900 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
12910 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
12920 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
12930 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
12940 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
12950 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
12960 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
12970 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12980 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64  G_MEMSTATUS]] <d
12990 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
129a0 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
129b0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
129c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
129d0 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TUS option takes
129e0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
129f0 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a   of type int,.**
12a00 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
12a10 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  a boolean, which
12a20 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
12a30 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
12a40 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79  ion of.** memory
12a50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
12a60 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
12a70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12a80 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a   statistics are.
12a90 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  ** disabled, the
12aa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
12ab0 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
12ac0 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
12ad0 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
12ae0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12af0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
12b00 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12b10 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
12b20 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
12b30 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
12b40 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
12b50 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12b60 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a  e3_status64()].*
12b70 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
12b80 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
12b90 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
12ba0 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
12bb0 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
12bc0 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
12bd0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
12be0 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
12bf0 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
12c00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
12c10 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12c20 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
12c30 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
12c40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12c50 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12c60 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12c70 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
12c80 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
12c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12ca0 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63  ATCH option spec
12cb0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
12cc0 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20  emory buffer.** 
12cd0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
12ce0 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 20  use for scratch 
12cf0 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65  memory.  ^(There
12d00 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
12d10 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54  ents.** to SQLIT
12d20 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12d30 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20  :  A pointer an 
12d40 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
12d50 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  d memory buffer 
12d60 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73  from which the s
12d70 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
12d80 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
12d90 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
12da0 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
12db0 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
12dc0 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
12dd0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
12de0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
12df0 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69  (N).)^.** The fi
12e00 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
12e10 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  t be a pointer t
12e20 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
12e30 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
12e40 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
12e50 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
12e60 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12e70 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61  not use more tha
12e80 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75  n one scratch bu
12e90 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
12ea0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12eb0 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 20  l never request 
12ec0 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
12ed0 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
12ee0 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
12ef0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12f00 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  size..** ^If SQL
12f10 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
12f20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
12f30 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
12f40 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
12f50 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
12f60 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12f70 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
12f80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
12f90 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
12fa0 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
12fb0 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e   needed.<p>.** ^
12fc0 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61  When the applica
12fd0 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e  tion provides an
12fe0 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61  y amount of scra
12ff0 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67  tch memory using
13000 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
13010 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74  G_SCRATCH, SQLit
13020 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73  e avoids unneces
13030 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73  sary large.** [s
13040 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65  qlite3_malloc|he
13050 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e  ap allocations].
13060 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c  .** This can hel
13070 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c  p [Robson proof|
13080 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61  prevent memory a
13090 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
130a0 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a  es] due to heap.
130b0 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  ** fragmentation
130c0 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65   in low-memory e
130d0 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
130e0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
130f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13100 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
13110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13120 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
13130 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13140 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13150 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  E option specifi
13160 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
13170 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  ry buffer.** tha
13180 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
13190 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
131a0 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
131b0 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
131c0 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
131d0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
131e0 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
131f0 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
13200 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
13210 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
13220 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13230 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
13240 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
13250 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13260 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66  PCACHE2].** conf
13270 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13280 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
13290 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
132a0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
132b0 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f  _PAGECACHE: A po
132c0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79  inter to.** 8-by
132d0 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
132e0 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
132f0 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
13300 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
13310 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
13320 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
13330 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
13340 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
13350 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
13360 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
13370 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
13380 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
13390 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
133a0 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
133b0 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
133c0 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
133d0 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
133e0 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
133f0 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
13400 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
13410 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
13420 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
13430 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74  SZ] option .** t
13440 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
13450 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  g()]..** ^It is 
13460 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
13470 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
13480 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74  memory,.** for t
13490 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
134a0 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  to be larger tha
134b0 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68  n necessary.  Th
134c0 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
134d0 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
134e0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
134f0 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66  aligned block of
13500 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20   memory that.** 
13510 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  is at least sz*N
13520 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
13530 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75 62 73  , otherwise subs
13540 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
13550 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
13560 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
13570 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
13580 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
13590 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
135a0 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
135b0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
135c0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
135d0 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
135e0 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
135f0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
13600 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
13610 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
13620 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
13630 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
13640 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
13650 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
13660 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
13670 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
13680 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64  torage space.</d
13690 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
136a0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
136b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
136c0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
136d0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
136e0 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
136f0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13700 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13710 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
13720 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
13730 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
13740 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
13750 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
13760 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
13770 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
13780 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13790 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  CH] and.** [SQLI
137a0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
137b0 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
137c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
137d0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
137e0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
137f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
13800 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
13810 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
13820 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
13830 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
13840 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
13850 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13860 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
13870 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
13880 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13890 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
138a0 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
138b0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
138c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
138d0 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
138e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
138f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
13900 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
13910 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13920 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
13930 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
13940 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
13950 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
13960 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
13970 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
13980 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
13990 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
139a0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
139b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
139c0 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
139d0 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
139e0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
139f0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
13a00 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
13a10 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
13a20 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
13a30 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
13a40 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
13a50 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
13a60 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
13a70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13a80 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
13a90 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
13aa0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
13ab0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
13ac0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
13ad0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
13ae0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
13af0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
13b00 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
13b10 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
13b20 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
13b30 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
13b40 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
13b50 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
13b60 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13b70 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
13b80 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
13b90 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13ba0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
13bb0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13bc0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
13bd0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13be0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
13bf0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13c00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13c10 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
13c20 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
13c30 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
13c40 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
13c50 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
13c60 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
13c70 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
13c80 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
13c90 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
13ca0 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
13cb0 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
13cc0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
13cd0 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
13ce0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
13cf0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
13d00 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
13d10 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
13d20 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
13d30 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
13d40 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13d50 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
13d60 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13d70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13d80 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13d90 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13da0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13db0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13dc0 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
13dd0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
13de0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
13df0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
13e00 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
13e10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13e20 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
13e30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13e40 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
13e50 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
13e60 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
13e70 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
13e80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13e90 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
13ea0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13eb0 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
13ec0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13ed0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
13ee0 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
13ef0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13f00 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
13f10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
13f20 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
13f30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13f40 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13f50 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
13f60 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
13f70 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
13f80 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
13f90 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
13fa0 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
13fb0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
13fc0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
13fd0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
13fe0 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
13ff0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
14000 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
14010 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
14020 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
14030 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
14040 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
14050 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
14060 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
14070 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14080 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14090 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
140a0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
140b0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
140c0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
140d0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
140e0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
140f0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
14100 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
14110 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
14120 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14130 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14140 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14150 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14160 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14170 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14180 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14190 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
141a0 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
141b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
141c0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
141d0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
141e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
141f0 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
14200 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
14210 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
14220 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
14230 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
14240 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
14250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14260 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
14270 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
14280 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14290 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
142a0 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
142b0 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
142c0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
142d0 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
142e0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
142f0 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
14300 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14310 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
14320 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
14330 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
14340 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
14350 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
14360 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
14370 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14380 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
14390 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
143a0 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
143b0 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
143c0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
143d0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
143e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
143f0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
14400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14410 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14420 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14430 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
14440 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14450 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14460 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14470 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14480 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14490 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
144a0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
144b0 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
144c0 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
144d0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
144e0 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
144f0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14500 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
14510 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14520 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
14530 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14540 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14550 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14560 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14570 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14580 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14590 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
145a0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
145b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
145c0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
145d0 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
145e0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
145f0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
14600 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
14610 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
14620 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14630 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
14640 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
14650 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14660 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
14670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14680 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
14690 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
146a0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
146b0 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
146c0 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
146d0 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
146e0 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
146f0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14700 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
14710 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
14720 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
14730 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
14740 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
14750 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
14760 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
14770 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
14780 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
14790 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
147a0 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
147b0 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
147c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
147d0 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
147e0 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
147f0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
14800 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
14810 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
14820 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
14830 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
14840 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
14850 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
14860 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
14870 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
14880 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
14890 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
148a0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
148b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
148c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
148d0 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
148e0 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
148f0 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
14900 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
14910 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14920 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
14930 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
14940 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
14950 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
14960 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
14970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
14980 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
14990 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
149a0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
149b0 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
149c0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
149d0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
149e0 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
149f0 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
14a00 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
14a10 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
14a20 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
14a30 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
14a40 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
14a50 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
14a60 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
14a70 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
14a80 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
14a90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
14aa0 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
14ab0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
14ac0 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
14ad0 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
14ae0 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
14af0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
14b00 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
14b10 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
14b20 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
14b30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14b40 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
14b50 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
14b60 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
14b70 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
14b80 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14b90 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
14ba0 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
14bb0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
14bc0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
14bd0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
14be0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
14bf0 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
14c00 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
14c10 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
14c20 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
14c30 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14c40 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
14c50 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
14c60 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
14c70 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
14c80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
14c90 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
14ca0 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
14cb0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
14cc0 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
14cd0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
14ce0 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
14cf0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
14d00 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
14d10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
14d20 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
14d30 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
14d40 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
14d50 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
14d60 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
14d70 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
14d80 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
14d90 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
14da0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
14db0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
14dc0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
14dd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14de0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
14df0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
14e00 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14e10 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
14e20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
14e30 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
14e40 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
14e50 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
14e60 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
14e70 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
14e80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14e90 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14ea0 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
14eb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14ec0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
14ed0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
14ee0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14ef0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
14f00 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14f10 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
14f20 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14f30 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
14f40 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
14f50 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
14f60 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
14f70 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
14f80 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
14f90 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
14fa0 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
14fb0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
14fc0 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
14fd0 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
14fe0 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
14ff0 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
15000 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
15010 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
15020 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
15030 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
15040 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
15050 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
15060 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
15070 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
15080 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15090 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
150a0 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
150b0 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
150c0 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
150d0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
150e0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
150f0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15100 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
15110 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
15120 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
15130 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
15140 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
15150 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
15160 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
15170 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
15180 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
15190 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
151a0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
151b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
151c0 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
151d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
151e0 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
151f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15200 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
15210 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
15220 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
15230 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
15240 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
15250 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
15260 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
15270 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
15280 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
15290 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
152a0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
152b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
152c0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
152d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
152e0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
152f0 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
15300 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15310 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
15320 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
15330 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
15340 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
15350 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15360 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
15370 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
15380 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
15390 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
153a0 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
153b0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
153c0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
153d0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
153e0 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
153f0 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
15400 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15410 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
15420 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
15430 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
15440 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
15450 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
15460 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
15470 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
15480 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
15490 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
154a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
154b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
154c0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
154d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
154e0 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
154f0 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
15500 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
15510 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
15520 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
15530 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
15540 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
15550 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
15560 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
15570 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
15580 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
15590 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
155a0 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
155b0 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
155c0 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
155d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
155e0 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
155f0 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
15600 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15610 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15620 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
15630 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
15640 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
15650 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
15660 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
15670 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
15680 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15690 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
156a0 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
156b0 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
156c0 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
156d0 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
156e0 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
156f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15700 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15710 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15720 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15730 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
15740 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15750 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
15760 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
15770 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
15780 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
15790 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
157a0 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
157b0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
157c0 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
157d0 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
157e0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
157f0 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
15800 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
15810 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
15820 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
15830 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
15840 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
15850 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
15860 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15870 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
15880 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
15890 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
158a0 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
158b0 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
158c0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
158d0 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
158e0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
158f0 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
15900 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
15910 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
15920 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
15930 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
15940 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
15950 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
15960 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
15970 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
15980 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
15990 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
159a0 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
159b0 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
159c0 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
159d0 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
159e0 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
159f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15a00 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15a10 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
15a20 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15a30 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
15a40 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15a50 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15a60 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
15a70 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
15a80 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
15a90 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
15aa0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
15ab0 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
15ac0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
15ad0 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
15ae0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15af0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
15b00 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
15b10 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
15b20 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
15b30 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
15b40 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
15b50 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
15b60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15b70 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
15b80 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
15b90 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
15ba0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
15bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15bc0 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
15bd0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
15be0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
15bf0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
15c00 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
15c10 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
15c20 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
15c30 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
15c40 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
15c50 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
15c60 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
15c70 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
15c80 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
15c90 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
15ca0 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
15cb0 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
15cc0 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
15cd0 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
15ce0 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
15cf0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
15d00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15d10 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
15d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
15d30 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
15d40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
15d50 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
15d60 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
15d70 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
15d80 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
15d90 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
15da0 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
15db0 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
15dc0 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
15dd0 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
15de0 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
15df0 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
15e00 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
15e10 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
15e20 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
15e30 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
15e40 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
15e50 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
15e60 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
15e70 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
15e80 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
15e90 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
15ea0 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
15eb0 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
15ec0 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
15ed0 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
15ee0 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
15ef0 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
15f00 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
15f10 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
15f20 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
15f30 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
15f40 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20   this value..** 
15f50 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
15f60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15f70 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
15f80 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15fa0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
15fb0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15fc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15fd0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
15fe0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15ff0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16000 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
16010 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
16020 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16040 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
16050 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
16060 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16080 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
16090 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
160a0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
160b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
160c0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
160d0 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
160e0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
160f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16100 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
16110 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
16120 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
16130 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
16140 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16150 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
16160 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
16170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16180 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
16190 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
161a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
161b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
161c0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
161d0 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
161e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
161f0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
16200 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
16210 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
16220 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
16230 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
16240 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16250 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
16260 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
16270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16280 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
16290 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
162a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
162b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
162c0 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
162d0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
162e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
162f0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
16300 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
16310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16320 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
16330 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
16340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16350 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
16360 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
16370 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16380 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
16390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
163a0 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
163b0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
163c0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
163d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
163e0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
163f0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
16400 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
16410 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
16420 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
16430 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
16440 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16450 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16460 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
16470 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
16480 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
16490 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
164a0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
164b0 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
164c0 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
164d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
164e0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
164f0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
16500 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
16510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16520 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
16530 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
16540 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a  int szPma */../*
16550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
16560 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
16570 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
16580 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
16590 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
165a0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
165b0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
165c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
165d0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
165e0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
165f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
16600 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
16610 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
16620 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
16630 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16640 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
16650 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
16660 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
16670 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
16680 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
16690 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
166a0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
166b0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
166c0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
166d0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
166e0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
166f0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
16700 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
16710 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
16720 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16730 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
16740 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
16750 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
16760 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
16770 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
16780 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
16790 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
167a0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
167b0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
167c0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
167d0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
167e0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
167f0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
16800 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
16810 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
16820 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
16830 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
16840 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
16850 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
16860 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
16870 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
16880 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
16890 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
168a0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
168b0 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
168c0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
168d0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
168e0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
168f0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
16900 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
16910 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
16920 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
16930 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
16940 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
16950 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
16960 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
16970 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
16980 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
16990 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
169a0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
169b0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
169c0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
169d0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
169e0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
169f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
16a00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
16a10 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
16a20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
16a30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16a40 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
16a50 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
16a60 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
16a70 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
16a80 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
16a90 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
16aa0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
16ab0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
16ac0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
16ad0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16ae0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
16af0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16b00 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
16b10 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
16b20 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
16b30 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
16b40 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
16b50 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
16b60 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
16b70 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
16b80 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
16b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16ba0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
16bb0 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
16bc0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
16bd0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
16be0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
16bf0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
16c00 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
16c10 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
16c20 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
16c30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
16c40 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
16c50 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16c60 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
16c70 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
16c80 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
16c90 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
16ca0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
16cb0 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
16cc0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
16cd0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
16ce0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
16cf0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
16d00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
16d10 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
16d20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
16d30 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
16d40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16d50 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
16d60 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
16d70 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
16d80 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
16d90 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
16da0 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
16db0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
16dc0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
16dd0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
16de0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
16df0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
16e00 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
16e10 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
16e20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
16e30 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
16e40 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
16e50 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
16e60 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
16e70 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
16e80 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
16e90 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
16ea0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
16eb0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
16ec0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
16ed0 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
16ee0 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
16ef0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
16f00 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
16f10 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16f20 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
16f30 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
16f40 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
16f50 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
16f60 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
16f70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
16f80 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
16f90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
16fa0 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
16fb0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
16fc0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
16fd0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
16fe0 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
16ff0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
17000 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17010 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17020 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17030 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17040 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
17050 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
17060 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
17070 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17080 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
17090 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
170a0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
170b0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
170c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
170d0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
170e0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
170f0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
17100 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
17110 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
17120 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
17130 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
17140 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17150 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17160 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17170 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17180 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17190 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
171a0 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
171b0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
171c0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
171d0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
171e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
171f0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
17200 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69  1001  /* void* i
17210 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
17220 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
17230 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
17240 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69    1002  /* int i
17250 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
17260 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17270 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31  NABLE_TRIGGER  1
17280 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  003  /* int int*
17290 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
172a0 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
172b0 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
172c0 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
172d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
172e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
172f0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
17300 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
17310 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
17320 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
17330 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
17340 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
17350 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
17360 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
17370 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
17380 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
17390 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
173a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
173b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
173c0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
173d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
173e0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
173f0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
17400 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17410 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
17420 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Rowid.** METHOD:
17430 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
17440 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
17450 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
17460 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
17470 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
17480 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
17490 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
174a0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
174b0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
174c0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
174d0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
174e0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
174f0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
17500 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
17510 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
17520 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
17530 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
17540 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
17550 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
17560 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
17570 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
17580 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
17590 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
175a0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
175b0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
175c0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
175d0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
175e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
175f0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17600 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
17610 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
17620 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
17630 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
17640 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17650 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
17660 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
17670 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
17680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17690 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72  ion D..** ^Inser
176a0 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
176b0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
176c0 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
176d0 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
176e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
176f0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
17700 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
17710 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
17720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17730 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
17740 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17750 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
17760 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
17770 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
17780 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
17790 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
177a0 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
177b0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
177c0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
177d0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
177e0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
177f0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
17800 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
17810 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
17820 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
17830 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
17840 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
17850 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
17860 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
17870 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
17880 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
17890 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
178a0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
178b0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
178c0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
178d0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
178e0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
178f0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
17900 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
17910 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
17920 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
17930 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
17940 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
17950 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
17960 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
17970 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
17980 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
17990 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
179a0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
179b0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
179c0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
179d0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
179e0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
179f0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
17a00 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
17a10 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
17a20 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
17a30 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
17a40 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
17a50 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
17a60 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
17a70 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
17a80 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
17a90 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
17aa0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
17ab0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
17ac0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
17ad0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
17ae0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
17af0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
17b00 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
17b10 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
17b20 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
17b30 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
17b40 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
17b50 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
17b60 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
17b70 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
17b80 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
17b90 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
17ba0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
17bb0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
17bc0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
17bd0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
17be0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
17bf0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
17c00 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17c10 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17c20 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
17c30 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
17c40 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
17c50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17c60 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
17c70 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17c80 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
17c90 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
17ca0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
17cb0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
17cc0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
17cd0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
17ce0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
17cf0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
17d00 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
17d10 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
17d20 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
17d30 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
17d40 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
17d50 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
17d60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
17d70 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
17d80 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
17d90 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17da0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
17db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17dc0 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
17dd0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17de0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
17df0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
17e00 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
17e10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
17e20 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20   rows modified, 
17e30 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64  inserted or.** d
17e40 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
17e50 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
17e60 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
17e70 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a  DATE or DELETE.*
17e80 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  * statement on t
17e90 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
17ea0 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
17eb0 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   by the only par
17ec0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63  ameter..** ^Exec
17ed0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
17ee0 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
17ef0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d  ement does not m
17f00 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a  odify the value.
17f10 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ** returned by t
17f20 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
17f30 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65  .** ^Only change
17f40 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20  s made directly 
17f50 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
17f60 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
17f70 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a  statement are.**
17f80 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75   considered - au
17f90 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
17fa0 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54  caused by [CREAT
17fb0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17fc0 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65  gers], .** [fore
17fd0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
17fe0 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   or [REPLACE] co
17ff0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
18000 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ion are not coun
18010 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e  ted..** .** Chan
18020 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
18030 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
18040 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45  ed by .** [INSTE
18050 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20  AD OF trigger | 
18060 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
18070 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ers] are not cou
18080 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65  nted. ^The value
18090 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79   .** returned by
180a0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
180b0 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  () immediately a
180c0 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20  fter an INSERT, 
180d0 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45  UPDATE or .** DE
180e0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72  LETE statement r
180f0 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20  un on a view is 
18100 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c  always zero. Onl
18110 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74  y changes made t
18120 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65  o real .** table
18130 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
18140 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20  *.** Things are 
18150 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64  more complicated
18160 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
18170 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
18180 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65  on is.** execute
18190 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65  d while a trigge
181a0 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e  r program is run
181b0 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68  ning. This may h
181c0 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20  appen if the.** 
181d0 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65  program uses the
181e0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
181f0 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66  function], or if
18200 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c   some other call
18210 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
18220 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33   invokes sqlite3
18230 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63  _changes() direc
18240 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79  tly. Essentially
18250 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
18260 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65     <li> ^(Before
18270 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67   entering a trig
18280 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20  ger program the 
18290 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
182a0 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69  y.**        sqli
182b0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
182c0 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e  nction is saved.
182d0 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67   After the trigg
182e0 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20  er program .**  
182f0 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68        has finish
18300 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ed, the original
18310 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72   value is restor
18320 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c  ed.)^.** .**   <
18330 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74  li> ^(Within a t
18340 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
18350 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ach INSERT, UPDA
18360 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a  TE and DELETE .*
18370 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65  *        stateme
18380 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75  nt sets the valu
18390 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
183a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
183b0 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20  .**        upon 
183c0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f  completion as no
183d0 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c  rmal. Of course,
183e0 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c   this value will
183f0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a   not include .**
18400 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e          any chan
18410 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ges performed by
18420 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61   sub-triggers, a
18430 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  s the sqlite3_ch
18440 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
18450 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65     value will be
18460 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f   saved and resto
18470 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73  red after each s
18480 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72  ub-trigger has r
18490 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  un.)^.** </ul>.*
184a0 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e  * .** ^This mean
184b0 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68  s that if the ch
184c0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
184d0 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72  tion (or similar
184e0 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20  ) is used.** by 
184f0 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54  the first INSERT
18500 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18510 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
18520 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69  hin a trigger, i
18530 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  t .** returns th
18540 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77  e value as set w
18550 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  hen the calling 
18560 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20  statement began 
18570 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49  executing..** ^I
18580 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20  f it is used by 
18590 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75  the second or su
185a0 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74  bsequent such st
185b0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
185c0 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f   trigger .** pro
185d0 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20  gram, the value 
185e0 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74  returned reflect
185f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18600 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79  rows modified by
18610 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75   the .** previou
18620 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  s INSERT, UPDATE
18630 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
18640 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
18650 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
18660 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
18670 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
18680 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
18690 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
186a0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
186b0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
186c0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
186d0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
186e0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
186f0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
18700 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
18710 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18720 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
18730 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
18740 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
18750 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18760 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
18770 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
18780 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  ingful..*/.SQLIT
18790 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
187a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
187b0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
187c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
187d0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
187e0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
187f0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
18800 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
18810 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
18820 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
18830 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
18840 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
18850 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
18860 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
18870 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
18880 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
18890 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
188a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
188b0 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
188c0 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
188d0 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
188e0 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
188f0 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
18900 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
18910 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
18920 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
18930 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
18940 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18950 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
18960 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
18970 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
18980 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
18990 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
189a0 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
189b0 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
189c0 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
189d0 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
189e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
189f0 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
18a00 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
18a10 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
18a20 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
18a30 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
18a40 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
18a50 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65  unted..** .** Se
18a60 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
18a70 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
18a80 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
18a90 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
18aa0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
18ab0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
18ac0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
18ad0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
18ae0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
18af0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
18b00 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
18b10 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
18b20 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
18b30 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
18b40 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
18b50 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
18b60 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
18b70 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
18b80 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  ingful..*/.SQLIT
18b90 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
18ba0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
18bb0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
18bc0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18bd0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
18be0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
18bf0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
18c00 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
18c10 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18c20 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
18c30 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
18c40 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
18c50 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
18c60 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
18c70 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
18c80 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
18c90 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
18ca0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
18cb0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
18cc0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
18cd0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
18ce0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
18cf0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
18d00 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
18d10 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
18d20 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
18d30 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
18d40 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
18d50 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
18d60 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
18d70 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
18d80 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
18d90 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
18da0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
18db0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
18dc0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
18dd0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
18de0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18df0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
18e00 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
18e10 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
18e20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18e30 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
18e40 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
18e50 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
18e60 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
18e70 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
18e80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18e90 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
18ea0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
18eb0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
18ec0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
18ed0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
18ee0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
18ef0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
18f00 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
18f10 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
18f20 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
18f30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
18f40 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
18f50 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
18f60 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
18f70 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
18f80 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
18f90 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
18fa0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
18fb0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
18fc0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
18fd0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
18fe0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
18ff0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
19000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
19010 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
19020 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
19030 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
19040 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
19050 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
19060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19070 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
19080 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
19090 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
190a0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
190b0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
190c0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
190d0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
190e0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
190f0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
19100 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
19110 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
19120 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
19130 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
19140 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19150 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
19160 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
19170 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
19180 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
19190 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
191a0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
191b0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
191c0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
191d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
191e0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
191f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19200 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
19210 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
19220 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
19230 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
19240 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
19250 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
19260 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
19270 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
19280 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
19290 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
192a0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
192b0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
192c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
192d0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
192e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
192f0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
19300 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
19310 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
19320 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
19330 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
19340 4c 4c 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  LL sqlite3_inter
19350 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
19360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19370 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
19380 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
19390 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
193a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
193b0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
193c0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
193d0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
193e0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
193f0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
19400 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
19410 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
19420 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
19430 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
19440 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
19450 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
19460 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
19470 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
19480 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
19490 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
194a0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
194b0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
194c0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
194d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
194e0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
194f0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
19500 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
19510 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
19520 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
19530 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
19540 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
19550 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
19560 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
19570 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
19580 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
19590 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
195a0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
195b0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
195c0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
195d0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
195e0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
195f0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
19600 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
19610 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
19620 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
19630 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
19640 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
19650 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
19660 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
19670 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
19680 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
19690 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
196a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
196b0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
196c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
196d0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
196e0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
196f0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
19700 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
19710 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
19720 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
19730 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
19740 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
19750 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
19760 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
19770 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
19780 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
19790 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
197a0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
197b0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
197c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
197d0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
197e0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
197f0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
19800 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
19810 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
19820 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
19830 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
19840 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
19850 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
19860 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
19870 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
19880 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
19890 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
198a0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
198b0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
198c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
198d0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
198e0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
198f0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
19900 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
19910 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
19920 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
19930 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
19940 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
19950 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
19960 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
19970 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
19980 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
19990 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
199a0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
199b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
199c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
199d0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
199e0 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c   char *sql);.SQL
199f0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
19a00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
19a10 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
19a20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
19a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19a40 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
19a50 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
19a60 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
19a70 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
19a80 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
19a90 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
19aa0 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  dler}.** METHOD:
19ab0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
19ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
19ad0 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20  _handler(D,X,P) 
19ae0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
19af0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19b00 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74   X.** that might
19b10 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
19b20 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
19b30 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
19b40 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  pt is made to ac
19b50 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20  cess a database 
19b60 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64  table associated
19b70 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61   with.** [databa
19b80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
19b90 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68   when another th
19ba0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
19bb0 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65  ss has the table
19bc0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20   locked..** The 
19bd0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
19be0 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  dler() interface
19bf0 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   is used to impl
19c00 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65  ement.** [sqlite
19c10 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
19c20 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75  ] and [PRAGMA bu
19c30 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a  sy_timeout]..**.
19c40 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
19c50 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
19c60 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
19c70 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  USY].** is retur
19c80 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
19c90 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
19ca0 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
19cb0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
19cc0 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
19cd0 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
19ce0 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
19cf0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
19d00 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
19d10 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
19d20 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
19d30 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
19d40 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
19d50 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
19d60 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
19d70 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
19d80 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
19d90 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
19da0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
19db0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
19dc0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
19dd0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
19de0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
19df0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
19e00 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73  invoked previous
19e10 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ly for the same 
19e20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
19e30 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
19e40 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19e50 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
19e60 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
19e70 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
19e80 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
19e90 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
19ea0 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
19eb0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
19ec0 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
19ed0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
19ee0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
19ef0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
19f00 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
19f10 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
19f20 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
19f30 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
19f40 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
19f50 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
19f60 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
19f70 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
19f80 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
19f90 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
19fa0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
19fb0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
19fc0 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
19fd0 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
19fe0 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
19ff0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1a000 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1a010 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1a020 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
1a030 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1a040 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
1a050 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
1a060 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
1a070 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
1a080 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
1a090 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1a0a0 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1a0b0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1a0c0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1a0d0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1a0e0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1a0f0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1a100 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1a110 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1a120 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1a130 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1a140 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1a150 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1a160 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1a170 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1a180 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1a190 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1a1a0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1a1b0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1a1c0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1a1d0 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1a1e0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1a1f0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1a200 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1a210 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1a220 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1a230 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1a240 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1a250 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1a260 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1a270 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1a280 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1a290 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1a2a0 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1a2b0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1a2c0 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1a2d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1a2e0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1a2f0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1a300 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1a310 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1a320 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1a330 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1a340 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
1a350 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
1a360 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
1a370 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
1a380 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
1a390 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
1a3a0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
1a3b0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
1a3c0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
1a3d0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
1a3e0 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
1a3f0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1a400 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
1a410 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
1a420 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
1a430 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
1a440 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
1a450 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1a460 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1a470 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1a480 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1a490 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1a4a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a4b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1a4c0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a4d0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
1a4e0 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
1a4f0 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
1a500 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
1a510 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1a520 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1a530 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1a540 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1a550 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1a560 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a570 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1a580 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1a590 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1a5a0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1a5b0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
1a5c0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1a5d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79  ALL sqlite3_busy
1a5e0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1a5f0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
1a600 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
1a610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1a620 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1a630 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1a640 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1a650 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1a660 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1a670 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1a680 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1a690 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1a6a0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1a6b0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1a6c0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1a6d0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1a6e0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1a6f0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1a700 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1a710 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1a720 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1a730 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1a740 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1a750 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1a760 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1a770 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1a780 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1a790 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a7a0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1a7b0 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1a7c0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1a7d0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1a7e0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1a7f0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1a800 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1a810 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1a820 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1a830 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1a840 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1a850 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1a860 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1a870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1a880 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1a890 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1a8a0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1a8b0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1a8c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1a8d0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1a8e0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1a8f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1a900 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1a910 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1a920 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1a930 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1a940 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53  sy_timeout].*/.S
1a950 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
1a960 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1a970 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a980 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1a990 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
1a9a0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
1a9b0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
1a9c0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
1a9d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1a9e0 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  3.**.** This is 
1a9f0 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
1aa00 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
1aa10 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
1aa20 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1aa30 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
1aa40 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
1aa50 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
1aa60 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
1aa70 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
1aa80 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
1aa90 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
1aaa0 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
1aab0 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1aac0 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
1aad0 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
1aae0 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
1aaf0 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
1ab00 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
1ab10 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
1ab20 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
1ab30 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
1ab40 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
1ab50 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
1ab60 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
1ab70 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
1ab80 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
1ab90 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
1aba0 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
1abb0 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
1abc0 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
1abd0 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
1abe0 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
1abf0 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
1ac00 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
1ac10 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1ac20 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1ac30 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
1ac40 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1ac50 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
1ac60 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
1ac70 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
1ac80 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
1ac90 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
1aca0 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
1acb0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1acc0 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
1acd0 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
1ace0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
1acf0 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
1ad00 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
1ad10 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
1ad20 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
1ad30 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
1ad40 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
1ad50 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
1ad60 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
1ad70 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1ad80 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
1ad90 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
1ada0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1adb0 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
1adc0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1add0 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
1ade0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
1adf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ae00 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
1ae10 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
1ae20 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
1ae30 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
1ae40 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
1ae50 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
1ae60 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
1ae70 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1ae80 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
1ae90 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
1aea0 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
1aeb0 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
1aec0 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
1aed0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
1aee0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1aef0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1af00 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
1af10 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
1af20 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
1af30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1af40 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
1af50 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
1af60 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
1af70 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
1af80 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
1af90 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
1afa0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1afb0 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
1afc0 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
1afd0 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
1afe0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
1aff0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
1b000 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
1b010 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
1b020 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
1b030 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
1b040 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
1b050 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
1b060 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
1b070 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b080 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1b090 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b0a0 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
1b0b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b0c0 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
1b0d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b0e0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
1b0f0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
1b100 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
1b110 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
1b120 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
1b130 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
1b140 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b150 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
1b160 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b170 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
1b180 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b190 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
1b1a0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1b1b0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1b1c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
1b1d0 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
1b1e0 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
1b1f0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
1b200 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
1b210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b220 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
1b230 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
1b240 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
1b250 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
1b260 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1b270 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
1b280 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
1b290 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
1b2a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
1b2b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1b2c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1b2d0 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
1b2e0 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
1b2f0 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
1b300 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
1b310 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
1b320 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1b330 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
1b340 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
1b350 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
1b360 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
1b370 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
1b380 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1b390 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
1b3a0 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
1b3b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
1b3c0 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
1b3d0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
1b3e0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
1b3f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
1b400 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
1b410 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1b420 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
1b430 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
1b440 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
1b450 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
1b460 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1b470 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
1b480 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
1b490 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
1b4a0 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
1b4b0 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
1b4c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b4d0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
1b4e0 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1b4f0 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
1b500 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
1b510 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
1b520 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
1b530 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
1b540 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
1b550 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
1b560 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
1b570 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
1b580 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
1b590 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
1b5a0 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
1b5b0 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
1b5c0 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
1b5d0 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
1b5e0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1b5f0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
1b600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1b610 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  msg()]..*/.SQLIT
1b620 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
1b630 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1b640 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1b650 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1b660 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1b670 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1b680 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1b690 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1b6a0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1b6b0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1b6c0 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1b6d0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1b6e0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1b6f0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1b700 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1b710 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1b720 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1b730 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1b740 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1b750 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1b760 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1b770 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1b780 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1b790 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
1b7a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
1b7b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1b7c0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1b7d0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1b7e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b7f0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1b800 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1b810 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1b820 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1b830 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1b840 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1b850 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1b860 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1b870 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1b880 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b890 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
1b8a0 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b   of the common K
1b8b0 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  &R formatting op
1b8c0 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73  tions,.** plus s
1b8d0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e  ome additional n
1b8e0 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d  on-standard form
1b8f0 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65  ats, detailed be
1b900 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  low..** Note tha
1b910 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f  t some of the mo
1b920 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61  re obscure forma
1b930 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72  tting options fr
1b940 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c  om recent.** C-l
1b950 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73  ibrary standards
1b960 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f   are omitted fro
1b970 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74  m this implement
1b980 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
1b990 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1b9a0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1b9b0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1b9c0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1b9d0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1b9e0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1b9f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1ba00 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1ba10 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1ba20 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1ba30 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1ba40 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1ba50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ba60 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1ba70 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1ba80 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1ba90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1baa0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1bab0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1bac0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1bad0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1bae0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1baf0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1bb00 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1bb10 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1bb20 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1bb30 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1bb40 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1bb50 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1bb60 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1bb70 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1bb80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1bb90 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1bba0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1bbb0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1bbc0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1bbd0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1bbe0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1bbf0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1bc00 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1bc10 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1bc20 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1bc30 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1bc40 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1bc50 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1bc60 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1bc70 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1bc80 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1bc90 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1bca0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1bcb0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1bcc0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1bcd0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1bce0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1bcf0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1bd00 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1bd10 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1bd20 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1bd30 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1bd40 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1bd50 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1bd60 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1bd70 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1bd80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1bd90 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1bda0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1bdb0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1bdc0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1bdd0 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1bde0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1bdf0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1be00 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1be10 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1be20 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1be30 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1be40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1be50 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1be60 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1be70 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1be80 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1be90 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1bea0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1beb0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1bec0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1bed0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1bee0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1bef0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1bf00 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1bf10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1bf20 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1bf30 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1bf40 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1bf50 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1bf60 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1bf70 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1bf80 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1bf90 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1bfa0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1bfb0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1bfc0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1bfd0 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1bfe0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1bff0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1c000 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1c010 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1c020 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1c030 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64  , "%Q", "%w" and
1c040 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1c050 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1c060 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1c070 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1c080 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1c090 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1c0a0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1c0b0 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1c0c0 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1c0d0 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1c0e0 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1c0f0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1c100 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1c110 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1c120 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1c130 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1c140 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1c150 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1c160 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1c170 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1c180 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1c190 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1c1a0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1c1b0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1c1c0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1c1d0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c1e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c1f0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1c200 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1c210 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1c220 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c230 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1c240 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1c250 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1c260 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1c270 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c280 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1c290 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1c2a0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1c2b0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1c2c0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1c2d0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1c2e0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1c2f0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1c300 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1c310 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c320 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1c330 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1c340 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1c350 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1c360 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1c370 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1c380 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1c390 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1c3a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1c3b0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1c3c0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1c3d0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1c3e0 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1c3f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1c400 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1c410 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1c420 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1c430 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1c440 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1c450 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1c460 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1c470 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c480 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1c490 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1c4a0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1c4b0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1c4c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c4d0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1c4e0 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1c4f0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1c500 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1c510 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1c520 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1c530 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1c540 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1c550 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1c560 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1c570 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1c580 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1c590 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1c5a0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1c5b0 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1c5c0 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1c5d0 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1c5e0 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1c5f0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1c600 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1c610 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1c620 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1c630 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1c640 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1c650 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1c660 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1c670 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1c680 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c690 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1c6a0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1c6b0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1c6c0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1c6d0 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1c6e0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1c6f0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1c700 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1c710 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1c720 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c730 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1c740 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1c750 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1c760 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1c770 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1c780 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1c790 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1c7a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1c7b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1c7c0 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1c7d0 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22  option is like "
1c7e0 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20  %q" except that 
1c7f0 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a  it expects to.**
1c800 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69   be contained wi
1c810 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  thin double-quot
1c820 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69  es instead of si
1c830 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64  ngle quotes, and
1c840 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74   it.** escapes t
1c850 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20  he double-quote 
1c860 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61  character instea
1c870 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d  d of the single-
1c880 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74  quote.** charact
1c890 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20  er.)^  The "%w" 
1c8a0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c8b0 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  n is intended fo
1c8c0 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69  r safely inserti
1c8d0 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20  ng.** table and 
1c8e0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74  column names int
1c8f0 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20  o a constructed 
1c900 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1c910 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1c920 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1c930 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1c940 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1c950 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1c960 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1c970 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1c980 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1c990 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1c9a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1c9b0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1c9c0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1c9d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  */.SQLITE_API ch
1c9e0 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c  ar *SQLITE_CDECL
1c9f0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1ca00 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1ca10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1ca20 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
1ca30 4c 4c 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  LL sqlite3_vmpri
1ca40 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1ca50 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54   va_list);.SQLIT
1ca60 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49  E_API char *SQLI
1ca70 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33  TE_CDECL sqlite3
1ca80 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1ca90 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1caa0 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50   ...);.SQLITE_AP
1cab0 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  I char *SQLITE_S
1cac0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
1cad0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1cae0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1caf0 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1cb00 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1cb10 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1cb20 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1cb30 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1cb40 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1cb50 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1cb60 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1cb70 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1cb80 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1cb90 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1cba0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1cbb0 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1cbc0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1cbd0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1cbe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1cbf0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1cc00 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1cc10 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1cc20 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1cc30 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1cc40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1cc50 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1cc60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1cc70 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1cc80 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1cc90 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1cca0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1ccb0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1ccc0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1ccd0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1cce0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1ccf0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1cd00 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1cd10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1cd20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1cd30 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1cd40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1cd50 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1cd60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1cd70 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1cd80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1cd90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1cda0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1cdb0 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1cdc0 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1cdd0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1cde0 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1cdf0 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1ce00 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1ce10 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1ce20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1ce30 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1ce40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1ce50 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1ce60 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1ce70 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1ce80 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1ce90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1cea0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1ceb0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1cec0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1ced0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1cee0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1cef0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1cf00 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1cf10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1cf20 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1cf30 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1cf40 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1cf50 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1cf60 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1cf70 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1cf80 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1cf90 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1cfa0 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1cfb0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1cfc0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1cfd0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1cfe0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1cff0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1d000 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1d010 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1d020 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1d030 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1d040 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1d050 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1d060 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1d070 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1d080 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1d090 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1d0a0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1d0b0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1d0c0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1d0d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1d0e0 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1d0f0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1d100 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1d110 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1d120 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1d130 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1d140 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1d150 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1d160 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1d170 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1d180 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1d190 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1d1a0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1d1b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1d1c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1d1d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1d1e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d1f0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1d200 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1d210 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1d220 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1d230 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1d240 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1d250 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1d260 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1d270 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1d280 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1d290 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1d2a0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1d2b0 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1d2c0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1d2d0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1d2e0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1d2f0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1d300 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1d310 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1d320 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1d330 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1d340 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1d350 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1d360 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1d370 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d380 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1d390 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1d3a0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1d3b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d3c0 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1d3d0 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1d3e0 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1d3f0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1d400 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1d410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d420 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1d430 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1d440 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1d450 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d460 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1d470 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1d480 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1d490 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1d4a0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1d4b0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1d4c0 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1d4d0 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1d4e0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1d4f0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1d500 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1d510 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1d520 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1d530 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1d540 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1d550 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1d560 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1d570 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1d580 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1d590 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1d5a0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1d5b0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1d5c0 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1d5d0 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1d5e0 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1d5f0 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1d600 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1d610 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1d620 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1d630 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1d640 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1d650 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1d660 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1d670 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1d680 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1d690 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1d6a0 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1d6b0 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1d6c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d6d0 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1d6e0 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1d6f0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1d700 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1d710 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1d720 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1d730 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1d740 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1d750 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1d760 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1d770 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1d780 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1d790 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1d7a0 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1d7b0 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1d7c0 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1d7d0 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1d7e0 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1d7f0 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1d800 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1d810 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1d820 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1d830 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1d840 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1d850 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1d860 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1d870 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1d880 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1d890 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1d8a0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1d8b0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1d8c0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1d8d0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1d8e0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1d8f0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1d900 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1d910 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1d920 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1d930 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1d940 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1d950 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1d960 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1d970 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1d980 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1d990 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1d9a0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1d9b0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1d9c0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1d9d0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1d9e0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1d9f0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1da00 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1da10 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1da20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1da30 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1da40 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1da50 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1da60 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1da70 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1da80 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1da90 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1daa0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1dab0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1dac0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1dad0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1dae0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1daf0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1db00 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1db10 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1db20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1db30 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1db40 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1db50 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1db60 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1db70 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1db80 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1db90 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1dba0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1dbb0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1dbc0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1dbd0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1dbe0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1dbf0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1dc00 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1dc10 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1dc20 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1dc30 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1dc40 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1dc50 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1dc60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1dc70 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1dc80 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
1dc90 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61  DCALL sqlite3_ma
1dca0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54  lloc(int);.SQLIT
1dcb0 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
1dcc0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1dcd0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1dce0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c  te3_uint64);.SQL
1dcf0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
1dd00 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1dd10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1dd20 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
1dd30 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
1dd40 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1dd50 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64  3_realloc64(void
1dd60 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
1dd70 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1dd80 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
1dd90 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  LL sqlite3_free(
1dda0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
1ddb0 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  PI sqlite3_uint6
1ddc0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
1ddd0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
1dde0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1ddf0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1de00 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1de10 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1de20 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1de30 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1de40 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1de50 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1de60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1de70 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1de80 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1de90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1dea0 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1deb0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1dec0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1ded0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1dee0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1def0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1df00 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1df10 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1df20 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1df30 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1df40 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1df50 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1df60 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1df70 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1df80 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1df90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1dfa0 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1dfb0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1dfc0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1dfd0 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1dfe0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1dff0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1e000 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1e010 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1e020 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1e030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1e040 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1e050 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1e060 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1e070 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1e080 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1e090 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e0a0 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1e0b0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1e0c0 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1e0d0 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1e0e0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1e0f0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1e100 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1e110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1e120 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1e130 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1e140 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1e150 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1e160 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1e170 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1e180 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1e190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1e1a0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1e1b0 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1e1c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1e1d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1e1e0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1e1f0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1e200 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1e210 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1e220 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
1e230 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
1e240 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1e250 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1e260 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1e270 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
1e280 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1e290 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e2a0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1e2b0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1e2c0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1e2d0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1e2e0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1e2f0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1e300 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1e310 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1e320 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1e330 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1e340 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1e350 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1e360 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1e370 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1e380 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1e390 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1e3a0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1e3b0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1e3c0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1e3d0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1e3e0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1e3f0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1e400 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1e410 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1e420 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1e430 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1e440 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1e450 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1e460 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1e470 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1e480 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1e490 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1e4a0 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20  ffer P..** ^The 
1e4b0 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  P parameter can 
1e4c0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1e4d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
1e4e0 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
1e4f0 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
1e500 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
1e510 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
1e520 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
1e530 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c  han one or a NUL
1e540 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c  L pointer for P,
1e550 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
1e560 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e  s.** seeded usin
1e570 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
1e580 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
1e590 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1e5a0 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61  d of.** the defa
1e5b0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1e5c0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
1e5d0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
1e5e0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1e5f0 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
1e600 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a   or more and a.*
1e610 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65  * non-NULL P the
1e620 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  n the pseudo-ran
1e630 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1e640 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1e650 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1e660 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1e670 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1e680 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1e690 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  od..*/.SQLITE_AP
1e6a0 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
1e6b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61  DCALL sqlite3_ra
1e6c0 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1e6d0 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1e6e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1e6f0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1e700 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1e710 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1e720 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1e730 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1e740 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1e750 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1e760 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1e770 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e780 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1e790 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1e7a0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
1e7b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e7c0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1e7d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1e7e0 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1e7f0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1e800 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1e810 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1e820 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e830 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1e840 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1e850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e860 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1e870 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1e880 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
1e890 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
1e8a0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
1e8b0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
1e8c0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
1e8d0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
1e8e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e8f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
1e900 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
1e910 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
1e920 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
1e930 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
1e940 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
1e950 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
1e960 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
1e970 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1e980 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
1e990 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
1e9a0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
1e9b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1e9c0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
1e9d0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
1e9e0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
1e9f0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
1ea00 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1ea10 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
1ea20 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
1ea30 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
1ea40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1ea50 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
1ea60 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1ea70 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
1ea80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
1ea90 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
1eaa0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
1eab0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1eac0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1ead0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1eae0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
1eaf0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1eb00 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1eb10 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
1eb20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1eb30 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1eb40 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
1eb50 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
1eb60 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
1eb70 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
1eb80 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1eb90 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
1eba0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1ebb0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1ebc0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1ebd0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
1ebe0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
1ebf0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1ec00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
1ec10 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
1ec20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
1ec30 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
1ec40 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1ec50 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ec60 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1ec70 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
1ec80 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1ec90 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
1eca0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
1ecb0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
1ecc0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
1ecd0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1ece0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
1ecf0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
1ed00 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
1ed10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
1ed20 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
1ed30 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1ed40 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
1ed50 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
1ed60 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
1ed70 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
1ed80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1ed90 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
1eda0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
1edb0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
1edc0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
1edd0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
1ede0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1edf0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1ee00 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
1ee10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1ee20 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
1ee30 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
1ee40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ee50 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
1ee60 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
1ee70 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
1ee80 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
1ee90 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
1eea0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
1eeb0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
1eec0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1eed0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1eee0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
1eef0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
1ef00 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
1ef10 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
1ef20 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
1ef30 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
1ef40 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
1ef50 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
1ef60 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1ef70 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
1ef80 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
1ef90 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1efa0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1efb0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
1efc0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
1efd0 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
1efe0 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
1eff0 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
1f000 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
1f010 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
1f020 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
1f030 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
1f040 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
1f050 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1f060 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
1f070 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
1f080 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
1f090 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
1f0a0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
1f0b0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
1f0c0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
1f0d0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
1f0e0 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
1f0f0 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
1f100 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
1f110 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
1f120 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
1f130 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
1f140 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
1f150 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
1f160 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
1f170 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
1f180 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
1f190 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
1f1a0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
1f1b0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
1f1c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1f1d0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
1f1e0 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
1f1f0 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
1f200 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
1f210 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
1f220 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
1f230 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
1f240 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
1f250 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
1f260 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
1f270 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f280 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
1f290 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
1f2a0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
1f2b0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
1f2c0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
1f2d0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
1f2e0 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
1f2f0 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
1f300 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
1f310 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
1f320 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
1f330 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
1f340 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1f350 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
1f360 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
1f370 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
1f380 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1f390 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
1f3a0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
1f3b0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
1f3c0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
1f3d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
1f3e0 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
1f3f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f400 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
1f410 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
1f420 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1f430 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
1f440 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
1f450 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
1f460 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
1f470 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
1f480 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
1f490 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
1f4a0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
1f4b0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1f4c0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1f4d0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1f4e0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1f4f0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1f500 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1f510 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1f520 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
1f530 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
1f540 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1f550 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f560 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1f570 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1f580 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1f590 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f5a0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1f5b0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1f5c0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1f5d0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
1f5e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f5f0 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
1f600 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
1f610 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
1f620 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
1f630 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
1f640 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1f650 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
1f660 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
1f670 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
1f680 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
1f690 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
1f6a0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
1f6b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1f6c0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
1f6d0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
1f6e0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1f6f0 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
1f700 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f710 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1f720 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
1f730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1f740 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1f750 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
1f760 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
1f770 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
1f780 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
1f790 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
1f7a0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
1f7b0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
1f7c0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1f7d0 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
1f7e0 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
1f7f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f800 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
1f810 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
1f820 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
1f830 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ange..*/.SQLITE_
1f840 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1f850 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
1f860 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1f870 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1f880 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1f890 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1f8a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1f8b0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1f8c0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1f8d0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1f8e0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1f8f0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1f900 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1f910 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f920 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1f930 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1f940 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1f950 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1f960 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1f970 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1f980 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1f990 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1f9a0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1f9b0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1f9c0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1f9d0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f9e0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1f9f0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1fa00 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1fa10 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1fa20 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1fa30 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1fa40 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1fa50 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
1fa60 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
1fa70 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
1fa80 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1fa90 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1faa0 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1fab0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1fac0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1fad0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1fae0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1faf0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1fb00 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1fb10 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1fb20 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1fb30 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1fb40 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1fb50 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1fb60 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1fb70 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1fb80 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1fb90 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1fba0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1fbb0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1fbc0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1fbd0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1fbe0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1fbf0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1fc00 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1fc10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1fc20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1fc30 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1fc40 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1fc50 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1fc60 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1fc70 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1fc80 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1fc90 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1fca0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fcb0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1fcc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1fcd0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1fce0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1fcf0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1fd00 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1fd10 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1fd20 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1fd30 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1fd40 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1fd50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1fd60 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1fd70 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1fd80 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1fd90 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1fda0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1fdb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1fdc0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1fdd0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1fde0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fdf0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1fe00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1fe10 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1fe20 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1fe30 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1fe40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1fe50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1fe60 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1fe70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1fe80 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1fe90 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1fea0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1feb0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1fec0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1fed0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1fee0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1fef0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1ff00 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1ff10 0a 2f 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 2a 2a 20 33 72  ************* 3r
1ff40 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1ff50 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1ff60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ff70 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1ff80 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1ff90 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1ffa0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ffb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ffc0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1ffd0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1ffe0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1fff0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20010 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
20020 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
20030 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
20040 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20050 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20060 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
20070 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
20080 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20090 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
200a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
200b0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
200c0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
200d0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
200e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
200f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20100 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
20110 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
20120 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20130 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20140 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
20150 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
20160 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
20170 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20180 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20190 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
201a0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
201b0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
201c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
201d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
201e0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
201f0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
20200 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20210 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20220 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20230 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
20240 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
20250 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20260 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20270 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20280 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
20290 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
202a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
202b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
202c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
202d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
202e0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
202f0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20300 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20320 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
20330 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
20340 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20350 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20370 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
20380 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
20390 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
203a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
203b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
203c0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
203d0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
203e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
203f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20410 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
20420 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
20430 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
20440 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20460 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
20470 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
20480 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
20490 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
204a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
204b0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
204c0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
204d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
204e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
204f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
20500 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
20510 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
20520 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
20530 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
20540 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
20550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20560 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
20570 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
20580 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
20590 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
205a0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
205b0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
205c0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
205d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
205e0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
205f0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
20600 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
20610 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20620 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20630 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
20640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
20650 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20660 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
20670 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
20680 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
20690 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
206a0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
206b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
206c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
206d0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
206e0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
206f0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
20700 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
20710 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20720 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
20730 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
20740 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
20750 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20760 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20770 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
20780 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
20790 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
207a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
207b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
207c0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
207d0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
207e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
207f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20810 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
20820 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
20830 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20840 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
20850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20860 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
20870 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
20880 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
20890 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
208a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
208b0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
208c0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
208d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
208e0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
208f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20900 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
20910 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
20920 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
20930 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
20940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20950 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
20960 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
20970 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
20980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
20990 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
209a0 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
209b0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
209c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
209d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
209e0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
209f0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
20a00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
20a10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
20a20 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
20a30 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20a40 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
20a50 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
20a60 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
20a70 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
20a80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
20a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
20aa0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
20ab0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
20ac0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
20ad0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
20ae0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
20af0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
20b00 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
20b10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
20b20 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
20b30 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
20b40 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
20b50 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
20b60 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
20b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
20b80 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
20b90 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
20ba0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
20bb0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
20bc0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
20bd0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
20be0 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
20bf0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
20c00 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
20c10 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
20c20 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
20c30 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
20c40 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
20c50 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
20c60 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
20c70 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
20c80 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
20c90 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
20ca0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
20cb0 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
20cc0 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
20cd0 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
20ce0 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
20cf0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
20d00 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
20d10 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20d20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
20d30 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
20d40 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
20d50 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
20d60 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
20d70 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
20d80 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
20d90 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
20da0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
20db0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
20dc0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
20dd0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
20de0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
20df0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
20e00 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
20e10 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
20e20 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
20e30 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
20e40 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
20e50 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
20e60 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
20e70 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
20e80 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
20e90 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
20ea0 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
20eb0 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
20ec0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
20ed0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
20ee0 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
20ef0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
20f00 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
20f10 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
20f20 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
20f30 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
20f40 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
20f50 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
20f60 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
20f70 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
20f80 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
20f90 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
20fa0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
20fb0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
20fc0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
20fd0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
20fe0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
20ff0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
21000 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
21010 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
21020 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
21030 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f  CALL sqlite3_pro
21040 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
21050 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
21060 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
21070 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
21080 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
21090 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
210a0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
210b0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
210c0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
210d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
210e0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
210f0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
21100 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
21110 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
21120 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
21130 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
21140 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
21150 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
21160 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
21170 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21180 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
21190 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
211a0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
211b0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
211c0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
211d0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
211e0 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
211f0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
21200 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
21210 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
21220 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
21230 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
21240 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
21250 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
21260 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
21270 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
21280 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
21290 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
212a0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
212b0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
212c0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
212d0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
212e0 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
212f0 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
21300 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
21310 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
21320 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
21330 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
21340 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
21350 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
21360 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
21370 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
21380 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
21390 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
213a0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
213b0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
213c0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
213d0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
213e0 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
213f0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
21400 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
21410 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
21420 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
21430 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
21440 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
21450 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
21460 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
21470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
21480 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
21490 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
214a0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
214b0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
214c0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
214d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
214e0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
214f0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
21500 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
21510 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
21520 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
21530 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
21540 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
21550 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
21560 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
21570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21580 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
21590 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
215a0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
215b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
215c0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
215d0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
215e0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
215f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21600 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
21610 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
21620 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
21630 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54  aph..**.*/.SQLIT
21640 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
21650 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
21660 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
21670 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
21680 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
21690 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
216a0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
216b0 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
216c0 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43   Connection.** C
216d0 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
216e0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
216f0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
21700 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
21710 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
21720 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
21730 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
21740 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
21750 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
21760 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
21770 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
21780 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21790 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
217a0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
217b0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
217c0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
217d0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
217e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
217f0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
21800 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
21810 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
21820 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
21830 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
21840 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
21850 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
21860 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
21870 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
21880 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
21890 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
218a0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
218b0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
218c0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
218d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
218e0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
218f0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
21900 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21910 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
21920 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
21930 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
21940 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
21950 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
21960 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
21970 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
21980 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
21990 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
219a0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
219b0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
219c0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
219d0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
219e0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
219f0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
21a00 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
21a10 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
21a20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21a30 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
21a40 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
21a50 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
21a60 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
21a70 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
21a80 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
21a90 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
21aa0 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
21ab0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
21ac0 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
21ad0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
21ae0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
21af0 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
21b00 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
21b10 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
21b20 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
21b30 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
21b40 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
21b50 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
21b60 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
21b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21b80 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
21b90 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
21ba0 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
21bb0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
21bc0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
21bd0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
21be0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
21bf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21c00 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
21c10 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
21c20 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
21c30 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
21c40 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
21c50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
21c60 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
21c70 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
21c80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21c90 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
21ca0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
21cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
21cc0 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
21cd0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
21ce0 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
21cf0 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
21d00 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
21d10 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
21d20 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
21d30 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
21d40 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
21d50 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
21d60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
21d70 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
21d80 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
21d90 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
21da0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
21db0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
21dc0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
21dd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21de0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
21df0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
21e00 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
21e10 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
21e20 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
21e30 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
21e40 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
21e50 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
21e60 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
21e70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
21e80 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21e90 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
21ea0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
21eb0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
21ec0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
21ed0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
21ee0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
21ef0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
21f00 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
21f10 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
21f20 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
21f30 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
21f40 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
21f50 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
21f60 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21f70 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
21f80 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
21f90 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
21fa0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
21fb0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21fc0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
21fd0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
21fe0 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
21ff0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
22000 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
22010 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
22020 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
22030 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
22040 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
22050 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
22060 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
22070 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
22080 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
22090 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
220a0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
220b0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
220c0 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
220d0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
220e0 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
220f0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
22100 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
22110 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
22120 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
22130 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
22140 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
22150 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
22160 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
22170 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22180 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
22190 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
221a0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
221b0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
221c0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
221d0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
221e0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
221f0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
22200 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
22210 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
22220 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
22230 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
22240 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22250 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
22260 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
22270 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
22280 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
22290 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
222a0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
222b0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
222c0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
222d0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
222e0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
222f0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
22300 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
22310 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
22320 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
22330 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
22340 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
22350 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
22360 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
22370 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
22380 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
22390 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
223a0 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
223b0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
223c0 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
223d0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
223e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
223f0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
22400 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
22410 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
22420 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
22430 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
22440 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
22450 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22460 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
22470 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22480 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
22490 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
224a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
224b0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
224c0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
224d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
224e0 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
224f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22500 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
22510 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
22520 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
22530 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
22540 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
22550 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
22560 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
22570 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
22580 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
22590 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
225a0 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
225b0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
225c0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
225d0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
225e0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
225f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22600 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
22610 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
22620 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
22630 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
22640 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
22650 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
22660 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
22670 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
22680 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
22690 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
226a0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
226b0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
226c0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
226d0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
226e0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
226f0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
22700 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
22710 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
22720 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
22730 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
22740 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
22750 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
22760 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
22770 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
22780 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
22790 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
227a0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
227b0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
227c0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
227d0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
227e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
227f0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
22800 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
22810 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
22820 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
22830 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
22840 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
22850 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
22860 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
22870 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
22880 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
22890 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
228a0 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
228b0 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
228c0 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
228d0 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
228e0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
228f0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
22900 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22910 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
22920 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
22930 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
22940 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
22950 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
22960 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
22970 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
22980 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
22990 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
229a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
229b0 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
229c0 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
229d0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
229e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
229f0 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
22a00 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
22a10 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
22a20 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
22a30 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
22a40 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
22a50 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
22a60 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
22a70 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
22a80 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
22a90 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
22aa0 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
22ab0 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
22ac0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
22ad0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
22ae0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
22af0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
22b00 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
22b10 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
22b20 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
22b30 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
22b40 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
22b50 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
22b60 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
22b70 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
22b80 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
22b90 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22ba0 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
22bb0 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
22bc0 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
22bd0 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
22be0 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
22bf0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
22c00 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
22c10 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
22c20 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
22c30 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
22c40 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
22c50 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
22c60 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
22c70 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
22c80 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
22c90 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
22ca0 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
22cb0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
22cc0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
22cd0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
22ce0 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
22cf0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
22d00 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
22d10 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
22d20 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
22d30 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
22d40 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
22d50 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
22d60 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
22d70 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
22d80 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
22d90 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
22da0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
22db0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
22dc0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
22dd0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
22de0 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
22df0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
22e00 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
22e10 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
22e20 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
22e30 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
22e40 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
22e50 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
22e60 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
22e70 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
22e80 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
22e90 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
22ea0 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
22eb0 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
22ec0 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
22ed0 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
22ee0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
22ef0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
22f00 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
22f10 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
22f20 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
22f30 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
22f40 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
22f50 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
22f60 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
22f70 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
22f80 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
22f90 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
22fa0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
22fb0 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
22fc0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
22fd0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
22fe0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
22ff0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
23000 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
23010 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
23020 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
23030 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
23040 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
23050 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
23060 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
23070 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
23080 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
23090 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
230a0 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
230b0 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
230c0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
230d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
230e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
230f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
23100 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
23110 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
23120 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
23130 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
23140 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
23150 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
23160 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
23170 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
23180 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
23190 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
231a0 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
231b0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
231c0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
231d0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
231e0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
231f0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
23200 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
23210 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
23220 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
23230 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
23240 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
23250 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
23260 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
23270 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
23280 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
23290 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
232a0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
232b0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
232c0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
232d0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
232e0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
232f0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
23300 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
23310 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
23320 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
23330 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
23340 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
23350 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
23360 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
23370 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
23380 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
23390 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
233a0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
233b0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
233c0 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
233d0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
233e0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
233f0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
23400 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
23410 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
23420 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
23430 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
23440 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
23450 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
23460 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
23470 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
23480 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
23490 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
234a0 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
234b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
234c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
234d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
234e0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
234f0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
23500 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
23510 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
23520 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
23530 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
23540 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
23550 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
23560 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
23570 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
23580 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
23590 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
235a0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
235b0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
235c0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
235d0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
235e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
235f0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
23600 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
23610 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
23620 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
23630 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
23640 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
23650 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
23660 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
23670 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
23680 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
23690 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
236a0 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
236b0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
236c0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
236d0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
236e0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
236f0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
23700 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
23710 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
23720 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
23730 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
23740 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
23750 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
23760 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
23770 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
23780 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
23790 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
237a0 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
237b0 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
237c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
237d0 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
237e0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
237f0 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
23800 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
23810 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
23820 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
23830 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
23840 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
23850 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
23860 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
23870 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
23880 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
23890 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
238a0 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
238b0 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
238c0 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
238d0 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
238e0 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
238f0 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
23900 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
23910 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
23920 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
23930 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
23940 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
23950 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
23960 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
23970 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
23980 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
23990 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
239a0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
239b0 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
239c0 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
239d0 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
239e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
239f0 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
23a00 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
23a10 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
23a20 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
23a30 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
23a40 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
23a50 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
23a60 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
23a70 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
23a80 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
23a90 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
23aa0 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
23ab0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
23ac0 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
23ad0 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
23ae0 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
23af0 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
23b00 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
23b10 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
23b20 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
23b30 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
23b40 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
23b50 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
23b60 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
23b70 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
23b80 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
23b90 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
23ba0 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
23bb0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
23bc0 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
23bd0 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
23be0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
23bf0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
23c00 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
23c10 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
23c20 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
23c30 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
23c40 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
23c50 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
23c60 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
23c70 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
23c80 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
23c90 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
23ca0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
23cb0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
23cc0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
23cd0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
23ce0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
23cf0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
23d00 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
23d10 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
23d20 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
23d30 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
23d40 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
23d50 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
23d60 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
23d70 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
23d80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23d90 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
23da0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23db0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
23dc0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
23dd0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
23de0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
23df0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23e00 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
23e10 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
23e20 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
23e30 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
23e40 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
23e50 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23e60 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
23e70 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
23e80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
23e90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23ea0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
23eb0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
23ec0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23ed0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
23ee0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
23ef0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
23f00 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
23f10 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
23f20 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
23f30 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
23f40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
23f50 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
23f60 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
23f70 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
23f80 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
23f90 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
23fa0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
23fb0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
23fc0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
23fd0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
23fe0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
23ff0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
24000 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
24010 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
24020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
24030 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
24040 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
24050 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
24060 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
24070 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
24080 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
24090 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
240a0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
240b0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
240c0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
240d0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
240e0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
240f0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
24100 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
24110 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
24120 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
24130 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
24140 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
24150 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
24160 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
24170 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
24180 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
24190 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
241a0 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
241b0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
241c0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
241d0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
241e0 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
241f0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
24200 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
24210 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
24220 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
24230 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
24240 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
24250 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
24260 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
24270 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
24280 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
24290 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
242a0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
242b0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
242c0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
242d0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
242e0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
242f0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
24300 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
24310 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
24320 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
24330 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
24340 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
24350 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
24360 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
24370 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
24380 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
24390 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
243a0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
243b0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
243c0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
243d0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
243e0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
243f0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
24400 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
24410 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
24420 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
24430 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
24440 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
24450 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
24460 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
24470 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
24480 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
24490 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
244a0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
244b0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
244c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
244d0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
244e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
244f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
24500 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
24510 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
24520 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
24530 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
24540 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
24550 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
24560 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
24570 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
24580 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
24590 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
245a0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
245b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
245c0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
245d0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
245e0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
245f0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
24600 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
24610 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
24620 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
24630 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
24640 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
24650 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
24660 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
24670 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
24680 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
24690 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
246a0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
246b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
246c0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
246d0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
246e0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
246f0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
24700 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
24710 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
24720 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
24730 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53  _directory].*/.S
24740 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
24750 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
24760 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
24770 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
24780 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
24790 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
247a0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
247b0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
247c0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
247d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
247e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
247f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
24800 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
24810 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
24820 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
24830 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
24840 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
24850 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
24860 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
24870 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
24880 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
24890 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
248a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
248b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
248c0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
248d0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
248e0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
248f0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
24900 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
24910 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
24920 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
24930 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
24940 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
24950 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
24960 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
24970 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
24980 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24990 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
249a0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
249b0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
249c0 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
249d0 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
249e0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
249f0 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
24a00 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
24a10 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
24a20 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
24a30 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
24a40 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
24a50 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
24a60 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
24a70 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
24a80 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
24a90 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
24aa0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
24ab0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
24ac0 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
24ad0 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
24ae0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
24af0 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
24b00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
24b10 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
24b20 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
24b30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
24b40 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
24b50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
24b60 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
24b70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24b80 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24b90 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
24ba0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24bb0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
24bc0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
24bd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
24be0 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
24bf0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
24c00 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
24c10 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
24c20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
24c30 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
24c40 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
24c50 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
24c60 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
24c70 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
24c80 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
24c90 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
24ca0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
24cb0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
24cc0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24cd0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
24ce0 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
24cf0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
24d00 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
24d10 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
24d20 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
24d30 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
24d40 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
24d50 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24d60 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
24d70 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
24d80 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
24d90 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
24da0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
24db0 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
24dc0 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
24dd0 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
24de0 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
24df0 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
24e00 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
24e10 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24e20 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
24e30 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
24e40 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
24e50 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
24e60 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
24e70 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
24e80 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
24e90 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
24ea0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
24eb0 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
24ec0 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
24ed0 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
24ee0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
24ef0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
24f00 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
24f10 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
24f20 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
24f30 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24f40 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
24f50 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
24f60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
24f70 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
24f80 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
24f90 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
24fa0 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
24fb0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
24fc0 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
24fd0 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
24fe0 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
24ff0 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
25000 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
25010 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
25020 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
25030 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
25040 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
25050 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
25060 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
25070 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
25080 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
25090 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
250a0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
250b0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
250c0 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
250d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
250e0 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
250f0 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
25100 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
25110 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
25120 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
25130 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
25140 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
25150 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
25160 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
25170 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
25180 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54  irable..*/.SQLIT
25190 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
251a0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
251b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
251c0 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
251d0 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
251e0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
251f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
25200 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
25210 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
25220 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
25230 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
25240 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
25250 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54  bDefault);.SQLIT
25260 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
25270 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
25280 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  LL sqlite3_uri_i
25290 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
252a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
252b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
252c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
252d0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
252e0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54   Messages.** MET
252f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
25300 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
25310 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a  recent sqlite3_*
25320 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
25330 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64  ated with .** [d
25340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25350 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68  on] D failed, th
25360 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  en the sqlite3_e
25370 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66  rrcode(D) interf
25380 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
25390 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
253a0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
253b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
253c0 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41  e] for that.** A
253d0 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74  PI call..** If t
253e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
253f0 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63  PI call was succ
25400 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20  essful,.** then 
25410 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
25420 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
25430 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
25440 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ined..** ^The sq
25450 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
25460 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
25470 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
25480 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
25490 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
254a0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
254b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
254c0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
254d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
254e0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
254f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25500 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
25510 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
25520 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
25530 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
25540 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
25550 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
25560 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
25570 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
25580 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
25590 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
255a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
255b0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
255c0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
255d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
255e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
255f0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
25600 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
25610 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
25620 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
25630 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
25640 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
25650 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
25660 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
25670 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
25680 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
25690 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
256a0 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
256b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
256c0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
256d0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
256e0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
256f0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
25700 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
25710 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
25720 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
25730 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
25740 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
25750 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
25760 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
25770 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
25780 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
25790 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
257a0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
257b0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
257c0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
257d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
257e0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
257f0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
25800 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
25810 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
25820 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
25830 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
25840 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
25850 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
25860 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
25870 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
25880 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
25890 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
258a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
258b0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
258c0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
258d0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
258e0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
258f0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
25900 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
25910 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
25920 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
25930 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
25940 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
25950 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
25960 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
25970 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
25980 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
25990 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
259a0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
259b0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
259c0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
259d0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
259e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
259f0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
25a00 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
25a10 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
25a20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
25a30 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
25a40 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
25a50 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
25a60 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
25a70 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
25a80 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
25a90 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
25aa0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
25ab0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
25ac0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
25ad0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
25ae0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
25af0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
25b00 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
25b10 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
25b20 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
25b30 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
25b40 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
25b50 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
25b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
25b70 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
25b80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
25b90 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
25ba0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
25bb0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
25bc0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
25bd0 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
25be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
25bf0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
25c00 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
25c10 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
25c20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
25c30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
25c40 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
25c50 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
25c60 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
25c70 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
25c80 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20  ent that.** has 
25c90 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e  been compiled in
25ca0 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61  to binary form a
25cb0 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62  nd is ready to b
25cc0 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
25cd0 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68  ** Think of each
25ce0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
25cf0 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d  s a separate com
25d00 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20  puter program.  
25d10 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  The.** original 
25d20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72  SQL text is sour
25d30 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70  ce code.  A prep
25d40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
25d50 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65  bject .** is the
25d60 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74   compiled object
25d70 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20   code.  All SQL 
25d80 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
25d90 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70  d into a.** prep
25da0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62  ared statement b
25db0 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20  efore it can be 
25dc0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  run..**.** The l
25dd0 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70  ife-cycle of a p
25de0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25df0 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79  t object usually
25e00 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a   goes like this:
25e10 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
25e20 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70  li> Create the p
25e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25e40 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  t object using [
25e50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
25e60 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  v2()]..** <li> B
25e70 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70  ind values to [p
25e80 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
25e90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
25ea0 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
25eb0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
25ec0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
25ed0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
25ee0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
25ef0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
25f00 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70  <li> Reset the p
25f10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25f20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
25f30 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
25f40 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
25f50 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
25f60 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
25f70 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
25f80 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
25f90 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
25fa0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
25fb0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65   </ol>.*/.typede
25fc0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
25fd0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
25fe0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
25ff0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
26000 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  mits.** METHOD: 
26010 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28  sqlite3.**.** ^(
26020 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
26030 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
26040 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
26050 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
26060 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
26070 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
26080 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
26090 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
260a0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
260b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
260c0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
260d0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
260e0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
260f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
26100 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
26110 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
26120 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
26130 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
26140 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
26150 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
26160 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
26170 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
26180 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
26190 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
261a0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
261b0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
261c0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
261d0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
261e0 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
261f0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
26200 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
26210 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
26220 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
26230 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
26240 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
26250 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
26260 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
26270 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
26280 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
26290 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
262a0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
262b0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
262c0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
262d0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
262e0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
262f0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
26300 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
26310 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
26320 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
26330 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
26340 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
26350 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
26360 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
26370 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
26380 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
26390 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
263a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
263b0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
263c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
263d0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
263e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
263f0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
26400 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
26410 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
26420 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
26430 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
26440 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
26450 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
26460 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
26470 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
26480 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
26490 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
264a0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
264b0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
264c0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
264d0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
264e0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
264f0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
26500 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
26510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
26520 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
26530 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
26540 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
26550 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
26560 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
26570 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
26580 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
26590 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
265a0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
265b0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
265c0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
265d0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
265e0 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
265f0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
26600 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
26610 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
26620 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
26630 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
26640 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
26650 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
26660 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
26670 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
26680 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
26690 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
266a0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
266b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
266c0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
266d0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
266e0 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
266f0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
26700 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
26710 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
26720 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
26730 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
26740 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
26750 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
26760 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
26770 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
26780 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
26790 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
267a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
267b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
267c0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
267d0 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  LL sqlite3_limit
267e0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
267f0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
26800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26810 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
26820 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
26830 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
26840 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
26850 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
26860 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
26870 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
26880 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
26890 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
268a0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
268b0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
268c0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
268d0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
268e0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
268f0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
26900 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
26910 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
26920 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
26930 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
26940 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
26950 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
26960 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
26970 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
26980 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
26990 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
269a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
269b0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
269c0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
269d0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
269e0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
269f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26a00 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
26a10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26a20 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
26a30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26a40 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26a50 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
26a60 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
26a70 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26a80 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
26a90 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26aa0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
26ab0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26ac0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
26ad0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
26ae0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
26af0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
26b00 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
26b10 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
26b20 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
26b30 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
26b40 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
26b50 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
26b60 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
26b70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26b80 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
26b90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26ba0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
26bb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26bc0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
26bd0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
26be0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
26bf0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26c00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
26c10 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
26c20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26c30 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
26c40 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
26c50 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26c60 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
26c70 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
26c80 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
26c90 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26ca0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
26cb0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26cc0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
26cd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26ce0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
26cf0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
26d00 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
26d10 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
26d20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
26d30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
26d40 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
26d50 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
26d60 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
26d70 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
26d80 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
26d90 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
26da0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
26db0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26dc0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
26dd0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
26de0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
26df0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
26e00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26e10 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
26e20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
26e30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26e40 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
26e50 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
26e60 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
26e70 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
26e80 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26e90 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
26ea0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
26eb0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
26ec0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
26ed0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
26ee0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
26ef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
26f00 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
26f10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26f20 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26f30 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
26f40 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
26f50 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
26f60 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
26f70 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26f80 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
26f90 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
26fa0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26fb0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
26fc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26fd0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
26fe0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
26ff0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
27000 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
27010 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27020 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
27030 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
27040 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
27050 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
27060 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
27070 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
27080 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
27090 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
270a0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
270b0 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
270c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
270d0 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
270e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
270f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
27100 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
27110 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
27120 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
27130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
27140 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
27150 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
27160 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27170 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
27180 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
27190 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
271a0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
271b0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
271c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
271d0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
271e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
271f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27200 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
27210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
27220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27230 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
27240 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
27250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27260 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
27270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27280 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
27290 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
272a0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
272b0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
272c0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
272d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
272e0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
272f0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
27300 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
27310 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
27320 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
27330 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
27340 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
27350 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
27360 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
27370 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
27380 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
27390 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
273a0 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
273b0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
273c0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
273d0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
273e0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
273f0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54  compiler}.** MET
27400 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
27410 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
27420 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
27430 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
27440 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
27450 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
27460 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
27470 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
27480 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
27490 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
274a0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
274b0 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
274c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
274d0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
274e0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
274f0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
27500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
27510 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
27520 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
27530 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
27540 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
27550 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
27560 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
27570 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
27580 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
27590 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
275a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
275b0 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
275c0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
275d0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
275e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
275f0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
27600 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27610 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
27620 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
27630 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27640 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
27650 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
27660 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
27670 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
27680 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
27690 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
276a0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
276b0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
276c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
276d0 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
276e0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
276f0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
27700 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
27710 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
27720 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
27730 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
27740 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
27750 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
27760 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
27770 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
27780 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
27790 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
277a0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
277b0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
277c0 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
277d0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
277e0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
277f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
27800 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
27810 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
27820 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
27830 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
27840 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
27850 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
27860 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
27870 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
27880 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
27890 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
278a0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
278b0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
278c0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
278d0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
278e0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
278f0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
27900 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
27910 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
27920 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
27930 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
27940 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
27950 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
27960 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
27970 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
27980 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
27990 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
279a0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
279b0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
279c0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
279d0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
279e0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
279f0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
27a00 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
27a10 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
27a20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
27a30 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
27a40 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
27a50 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
27a60 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
27a70 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
27a80 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
27a90 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
27aa0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
27ab0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
27ac0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
27ad0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
27ae0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
27af0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
27b00 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
27b10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27b20 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
27b30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
27b40 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
27b50 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
27b60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
27b70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
27b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27b90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
27ba0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
27bb0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
27bc0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
27bd0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
27be0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
27bf0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
27c00 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
27c10 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
27c20 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
27c30 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
27c40 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
27c50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
27c60 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
27c70 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
27c80 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
27c90 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
27ca0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
27cb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
27cc0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
27cd0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
27ce0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
27cf0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
27d00 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
27d10 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
27d20 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
27d30 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
27d40 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
27d50 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
27d60 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
27d70 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
27d80 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
27d90 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
27da0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27db0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
27dc0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
27dd0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
27de0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
27df0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
27e00 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
27e10 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
27e20 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
27e30 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
27e40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
27e50 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
27e60 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
27e70 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
27e80 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
27e90 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
27ea0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
27eb0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
27ec0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
27ed0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
27ee0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
27ef0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
27f00 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
27f10 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
27f20 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
27f30 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
27f40 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
27f50 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
27f60 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
27f70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
27f80 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
27f90 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
27fa0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
27fb0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
27fc0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
27fd0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
27fe0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
27ff0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
28000 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
28010 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
28020 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
28030 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
28040 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
28050 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
28060 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
28070 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
28080 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
28090 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
280a0 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
280b0 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
280c0 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
280d0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
280e0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
280f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
28100 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
28110 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
28120 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
28130 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
28140 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
28150 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
28160 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28170 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
28180 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
28190 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
281a0 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
281b0 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
281c0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
281d0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
281e0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
281f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
28200 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
28210 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
28220 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
28230 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28240 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
28250 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
28260 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
28270 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
28280 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
28290 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
282a0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
282b0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
282c0 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
282d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
282e0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69  enabled..** </li
282f0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51  >.** </ol>.*/.SQ
28300 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
28310 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
28320 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
28330 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
28340 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
28350 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
28360 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
28370 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
28380 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
28390 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
283a0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
283b0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
283c0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
283d0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
283e0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
283f0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
28400 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
28410 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
28420 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
28430 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
28440 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
28450 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
28460 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
28470 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
28480 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
28490 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
284a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
284b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
284c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
284d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
284e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
284f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
28500 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
28510 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
28520 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
28530 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
28540 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
28550 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
28560 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
28570 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
28580 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
28590 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
285a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
285b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
285c0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
285d0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
285e0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
285f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
28600 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
28610 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
28620 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
28630 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
28640 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
28650 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
28660 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
28670 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
28680 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
28690 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
286a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
286b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
286c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
286d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
286e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
286f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
28700 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
28710 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
28720 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
28730 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
28740 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
28750 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28760 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28770 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28780 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
28790 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
287a0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
287b0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
287c0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
287d0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
287e0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
287f0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28800 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28810 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28820 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28830 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28840 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28850 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28860 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28870 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
28880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28890 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
288a0 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
288b0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
288c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
288d0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
288e0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
288f0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
28900 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
28910 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
28920 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
28930 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
28940 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
28950 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
28960 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
28970 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
28980 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
28990 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
289a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
289b0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
289c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
289d0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
289e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
289f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
28a00 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
28a10 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
28a20 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
28a30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
28a40 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
28a50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
28a60 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
28a70 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
28a80 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
28a90 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
28aa0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28ab0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
28ac0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
28ad0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
28ae0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
28af0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
28b00 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
28b10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
28b20 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
28b30 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
28b40 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
28b50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
28b60 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
28b70 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
28b80 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
28b90 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
28ba0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
28bb0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
28bc0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
28bd0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
28be0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
28bf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
28c00 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
28c10 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28c20 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
28c30 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
28c40 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
28c50 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
28c60 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
28c70 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
28c80 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
28c90 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
28ca0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
28cb0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
28cc0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
28cd0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
28ce0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
28cf0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
28d00 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
28d10 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
28d20 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
28d30 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
28d40 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
28d50 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
28d60 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
28d70 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
28d80 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
28d90 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
28da0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
28db0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
28dc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
28dd0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
28de0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
28df0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
28e00 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
28e10 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
28e20 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
28e30 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
28e40 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
28e50 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
28e60 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
28e70 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
28e80 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
28e90 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
28ea0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
28eb0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
28ec0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
28ed0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
28ee0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
28ef0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
28f00 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
28f10 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
28f20 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
28f30 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
28f40 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
28f50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
28f60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
28f70 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  L sqlite3_stmt_r
28f80 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
28f90 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
28fa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28fb0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
28fc0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
28fd0 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
28fe0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28ff0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
29000 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
29010 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
29020 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
29030 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
29040 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
29050 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
29060 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
29070 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
29080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
29090 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
290a0 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
290b0 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
290c0 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
290d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
290e0 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
290f0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
29100 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
29110 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
29120 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
29130 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
29140 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
29150 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
29160 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
29170 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
29180 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
29190 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
291a0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
291b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
291c0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
291d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
291e0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
291f0 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
29200 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
29210 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
29220 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
29230 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
29240 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
29250 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
29260 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
29270 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
29280 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
29290 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
292a0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
292b0 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
292c0 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
292d0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
292e0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
292f0 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
29300 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
29310 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29320 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
29330 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
29340 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
29350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29360 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
29370 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
29380 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
29390 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
293a0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
293b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
293c0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
293d0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
293e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
293f0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
29400 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
29410 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
29420 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
29430 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
29440 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
29450 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
29460 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
29470 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
29480 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29490 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
294a0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
294b0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
294c0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
294d0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
294e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
294f0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
29500 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
29510 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
29520 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
29530 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
29540 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29550 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
29560 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
29570 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
29580 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
29590 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
295a0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
295b0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
295c0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
295d0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
295e0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
295f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
29600 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
29610 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29620 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
29630 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
29640 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
29650 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
29660 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
29670 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
29680 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
29690 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
296a0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
296b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
296c0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
296d0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
296e0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
296f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29700 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
29710 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
29720 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
29730 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
29740 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
29750 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
29760 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
29770 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
29780 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
29790 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
297a0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
297b0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
297c0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
297d0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
297e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
297f0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
29800 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
29810 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
29820 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
29830 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
29840 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
29850 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
29860 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
29870 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
29880 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
29890 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
298a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
298b0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
298c0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
298d0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
298e0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
298f0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
29900 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
29910 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
29920 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
29930 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
29940 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
29950 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
29960 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
29970 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
29980 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
29990 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
299a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
299b0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
299c0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
299d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
299e0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
299f0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
29a00 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
29a10 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
29a20 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
29a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29a40 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
29a50 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
29a60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
29a70 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
29a80 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
29a90 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
29aa0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
29ab0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
29ac0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
29ad0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
29ae0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
29af0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29b00 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
29b10 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
29b20 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
29b30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
29b40 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
29b50 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
29b60 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
29b70 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
29b80 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
29b90 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
29ba0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
29bb0 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
29bc0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
29bd0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
29be0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
29bf0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
29c00 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
29c10 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
29c20 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
29c30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29c40 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
29c50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
29c60 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
29c70 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
29c80 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
29c90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29ca0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
29cb0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
29cc0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
29cd0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
29ce0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
29cf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
29d00 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
29d10 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
29d20 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
29d30 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
29d40 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
29d50 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
29d60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
29d70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
29d80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29d90 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
29da0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
29db0 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
29dc0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
29dd0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
29de0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
29df0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
29e00 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
29e10 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
29e20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
29e30 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
29e40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29e50 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
29e60 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
29e70 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
29e80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
29e90 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
29ea0 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
29eb0 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
29ec0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
29ed0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
29ee0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
29ef0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
29f00 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
29f10 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
29f20 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
29f30 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
29f40 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
29f50 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
29f60 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
29f70 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
29f80 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
29f90 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
29fa0 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
29fb0 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
29fc0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
29fd0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
29fe0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
29ff0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2a000 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2a010 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2a020 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2a030 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2a040 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2a050 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2a060 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2a070 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2a080 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2a090 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2a0a0 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2a0b0 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2a0c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2a0d0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2a0e0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2a0f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a100 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2a110 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2a120 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2a130 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2a140 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2a150 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2a160 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2a170 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2a180 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2a190 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2a1a0 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2a1b0 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2a1c0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2a1d0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2a1e0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2a1f0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2a200 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2a210 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2a220 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2a230 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2a240 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2a250 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2a260 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2a270 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2a280 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2a290 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2a2a0 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2a2b0 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2a2c0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2a2d0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2a2e0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2a2f0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2a300 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2a310 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2a320 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2a330 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2a340 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2a350 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2a360 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2a370 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2a380 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2a390 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2a3a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2a3b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2a3c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2a3d0 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
2a3e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a3f0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
2a400 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
2a410 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
2a420 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
2a430 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
2a440 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
2a450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2a460 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
2a470 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
2a480 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
2a490 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
2a4a0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2a4b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2a4c0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
2a4d0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
2a4e0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
2a4f0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
2a500 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
2a510 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
2a520 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2a530 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
2a540 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2a550 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2a560 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2a570 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2a580 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
2a590 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
2a5a0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
2a5b0 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
2a5c0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
2a5d0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2a5e0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
2a5f0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2a600 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2a610 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2a620 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2a630 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2a640 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2a650 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2a660 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2a670 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2a680 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2a690 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2a6a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2a6b0 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2a6c0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2a6d0 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2a6e0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2a6f0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2a700 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2a710 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2a720 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2a730 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2a740 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2a750 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2a760 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2a770 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2a780 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2a790 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2a7a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2a7b0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2a7c0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2a7d0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2a7e0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2a7f0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2a800 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2a810 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2a820 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2a830 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2a840 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2a850 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2a860 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2a870 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2a880 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2a890 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2a8a0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2a8b0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2a8c0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2a8d0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2a8e0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2a8f0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2a900 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2a910 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2a920 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2a930 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2a940 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2a950 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2a960 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2a970 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2a980 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2a990 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2a9a0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2a9b0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2a9c0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2a9d0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2a9e0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
2a9f0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2aa00 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
2aa10 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2aa20 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2aa30 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2aa40 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2aa50 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2aa60 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2aa70 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2aa80 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2aa90 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2aaa0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2aab0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2aac0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2aad0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2aae0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2aaf0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2ab00 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2ab10 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2ab20 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2ab30 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2ab40 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2ab50 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2ab60 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2ab70 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2ab80 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2ab90 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2aba0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2abb0 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2abc0 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2abd0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2abe0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2abf0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2ac00 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2ac10 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2ac20 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2ac30 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2ac40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2ac50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2ac60 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2ac70 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2ac80 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2ac90 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2aca0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2acb0 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2acc0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2acd0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2ace0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2acf0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2ad00 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2ad10 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2ad20 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2ad30 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2ad40 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2ad50 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2ad60 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2ad70 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2ad80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2ad90 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2ada0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2adb0 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2adc0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2add0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2ade0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2adf0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2ae00 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2ae10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2ae20 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2ae30 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2ae40 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2ae50 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2ae60 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2ae70 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2ae80 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2ae90 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
2aea0 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
2aeb0 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
2aec0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
2aed0 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
2aee0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
2aef0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
2af00 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
2af10 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
2af20 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
2af30 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
2af40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2af50 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
2af60 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
2af70 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2af80 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
2af90 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
2afa0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2afb0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2afc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2afd0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2afe0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2aff0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2b000 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
2b010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2b020 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2b030 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2b040 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2b050 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2b060 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2b070 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2b080 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
2b090 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
2b0a0 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
2b0b0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
2b0c0 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
2b0d0 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
2b0e0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2b0f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
2b100 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
2b110 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
2b120 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2b130 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2b140 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2b150 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2b160 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2b170 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2b180 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2b190 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2b1a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2b1b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b1c0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2b1d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b1e0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2b1f0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2b200 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b210 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2b220 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2b230 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2b240 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
2b250 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2b260 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
2b270 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2b280 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2b290 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2b2a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2b2b0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2b2c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2b2d0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2b2e0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2b2f0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2b300 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2b310 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2b320 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2b330 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2b340 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b350 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
2b360 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2b370 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2b380 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2b390 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2b3a0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  t);.SQLITE_API i
2b3b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2b3c0 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  L sqlite3_bind_i
2b3d0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2b3e0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2b3f0 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  _int64);.SQLITE_
2b400 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b410 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2b420 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
2b430 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  _stmt*, int);.SQ
2b440 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2b450 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2b460 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
2b470 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c  lite3_stmt*,int,
2b480 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c  const char*,int,
2b490 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b4a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b4b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2b4c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2b4d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2b4e0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2b4f0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2b500 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2b510 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2b520 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2b530 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
2b540 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b550 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
2b560 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2b570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b580 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2b590 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
2b5a0 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53  har encoding);.S
2b5b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b5c0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b5d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2b5e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b5f0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2b600 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2b610 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2b620 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2b630 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2b640 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b650 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
2b660 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2b670 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
2b680 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ters.** METHOD: 
2b690 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b6a0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2b6b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2b6c0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
2b6d0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
2b6e0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
2b6f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b700 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
2b710 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
2b720 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
2b730 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
2b740 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
2b750 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
2b760 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2b770 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
2b780 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
2b790 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
2b7a0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
2b7b0 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
2b7c0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
2b7d0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
2b7e0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
2b7f0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
2b800 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
2b810 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
2b820 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
2b830 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
2b840 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
2b850 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
2b860 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
2b870 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
2b880 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
2b890 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
2b8a0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
2b8b0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
2b8c0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
2b8d0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2b8e0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2b8f0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2b900 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b910 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2b920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2b930 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2b940 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2b950 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b960 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2b970 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2b980 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2b990 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2b9a0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2b9b0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2b9c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b9d0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2b9e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2b9f0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2ba00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ba10 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2ba20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2ba30 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2ba40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ba50 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2ba60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2ba70 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2ba80 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2ba90 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2baa0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2bab0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2bac0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2bad0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2bae0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2baf0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2bb00 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2bb10 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2bb20 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2bb30 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2bb40 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2bb50 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2bb60 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2bb70 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2bb80 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2bb90 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2bba0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2bbb0 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2bbc0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2bbd0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2bbe0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2bbf0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2bc00 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2bc10 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2bc20 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2bc30 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2bc40 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2bc50 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2bc60 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2bc70 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2bc80 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2bc90 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2bca0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2bcb0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2bcc0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2bcd0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2bce0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2bcf0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
2bd00 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
2bd10 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2bd20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2bd30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2bd40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2bd50 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2bd60 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2bd70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2bd80 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2bd90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bda0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2bdb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2bdc0 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
2bdd0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2bde0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2bdf0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2be00 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
2be10 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
2be20 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
2be30 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
2be40 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
2be50 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2be60 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
2be70 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
2be80 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
2be90 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
2bea0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
2beb0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
2bec0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
2bed0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
2bee0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2bef0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2bf00 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
2bf10 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
2bf20 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
2bf30 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
2bf40 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
2bf50 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
2bf60 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
2bf70 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
2bf80 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
2bf90 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
2bfa0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
2bfb0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
2bfc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2bfd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2bfe0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2bff0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2c000 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2c010 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c020 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2c030 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2c040 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2c050 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
2c060 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2c070 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2c080 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2c090 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
2c0a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
2c0b0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
2c0c0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2c0d0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
2c0e0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2c0f0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
2c100 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c110 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
2c120 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
2c130 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
2c140 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
2c150 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
2c160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c170 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
2c180 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2c190 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
2c1a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2c1b0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
2c1c0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
2c1d0 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
2c1e0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2c1f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  ALL sqlite3_clea
2c200 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2c210 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2c220 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2c230 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
2c240 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2c250 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2c260 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
2c270 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2c280 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2c290 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2c2a0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2c2b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c2c0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2c2d0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2c2e0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2c2f0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2c300 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2c310 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2c320 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2c330 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2c340 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2c350 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
2c360 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2c370 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2c380 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
2c390 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2c3a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2c3b0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
2c3c0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
2c3d0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2c3e0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2c3f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2c400 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2c410 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2c420 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2c430 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2c440 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2c450 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2c460 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2c470 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2c480 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2c490 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2c4a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2c4b0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2c4c0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2c4d0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2c4e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2c4f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2c500 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2c510 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2c520 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c530 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c540 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2c550 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2c560 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2c570 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2c580 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2c590 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2c5a0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2c5b0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2c5c0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2c5d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2c5e0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2c5f0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2c600 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c610 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2c620 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2c630 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2c640 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2c650 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2c660 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2c670 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2c680 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2c690 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2c6a0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2c6b0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2c6c0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2c6d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2c6e0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2c6f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2c700 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2c710 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2c720 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2c730 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2c740 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2c750 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2c760 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2c770 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2c780 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2c790 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2c7a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2c7b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2c7c0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2c7d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2c7e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2c7f0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2c800 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2c810 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2c820 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2c830 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2c840 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2c850 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2c860 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2c870 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2c880 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2c890 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2c8a0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2c8b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2c8c0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
2c8d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2c8e0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
2c8f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2c900 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2c910 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
2c920 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2c930 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
2c940 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2c950 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
2c960 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
2c970 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
2c980 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
2c990 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c9a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2c9b0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2c9c0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2c9d0 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2c9e0 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2c9f0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2ca00 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2ca10 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2ca20 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2ca30 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ca40 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2ca50 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2ca60 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2ca70 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2ca80 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2ca90 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2caa0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2cab0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2cac0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2cad0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2cae0 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2caf0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2cb00 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2cb10 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2cb20 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2cb30 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2cb40 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2cb50 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2cb60 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2cb70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cb80 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2cb90 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2cba0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2cbb0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2cbc0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2cbd0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2cbe0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2cbf0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2cc00 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2cc10 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2cc20 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2cc30 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2cc40 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2cc50 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2cc60 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2cc70 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2cc80 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2cc90 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2cca0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2ccb0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2ccc0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2ccd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2cce0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2ccf0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2cd00 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2cd10 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2cd20 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2cd30 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2cd40 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2cd50 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2cd60 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2cd70 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2cd80 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2cd90 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2cda0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2cdb0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2cdc0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2cdd0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2cde0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2cdf0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2ce00 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2ce10 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2ce20 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2ce30 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2ce40 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2ce50 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2ce60 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2ce70 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2ce80 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2ce90 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2cea0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2ceb0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2cec0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2ced0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2cee0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2cef0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2cf00 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2cf10 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2cf20 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2cf30 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2cf40 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2cf50 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2cf60 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2cf70 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2cf80 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2cf90 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2cfa0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2cfb0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2cfc0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2cfd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2cfe0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2cff0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2d000 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2d010 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2d020 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2d030 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2d040 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2d050 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2d060 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2d070 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2d080 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2d090 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2d0a0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2d0b0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2d0c0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2d0d0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2d0e0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2d0f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2d100 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2d110 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2d120 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2d130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2d140 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2d150 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2d160 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2d170 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2d180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2d190 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2d1a0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2d1b0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2d1c0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2d1d0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2d1e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2d1f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2d200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2d210 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
2d220 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2d230 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2d240 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
2d250 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2d260 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2d270 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d280 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2d290 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
2d2a0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2d2b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2d2c0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2d2d0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2d2e0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2d2f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
2d300 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d310 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2d320 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d330 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d340 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
2d350 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2d360 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2d370 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d380 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2d390 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
2d3a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2d3b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2d3c0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2d3d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2d3e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
2d3f0 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
2d400 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
2d410 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d420 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2d430 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2d440 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2d450 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2d460 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2d470 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2d480 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2d490 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2d4a0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2d4b0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2d4c0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2d4d0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2d4e0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2d4f0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2d500 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2d510 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2d520 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2d530 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2d540 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2d550 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2d560 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2d570 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2d580 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2d590 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2d5a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2d5b0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2d5c0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2d5d0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2d5e0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2d5f0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2d600 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2d610 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2d620 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2d630 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2d640 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2d650 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2d660 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2d670 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2d680 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2d690 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2d6a0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2d6b0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2d6c0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2d6d0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2d6e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2d6f0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2d700 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2d710 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2d720 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2d730 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2d740 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2d750 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2d760 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2d770 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2d780 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2d790 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2d7a0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2d7b0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2d7c0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2d7d0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2d7e0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2d7f0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2d800 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2d810 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2d820 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2d830 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2d840 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2d850 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2d860 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2d870 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2d880 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2d890 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54  onst char *SQLIT
2d8a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d8b0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2d8c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d8d0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2d8e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
2d8f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2d900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2d910 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2d920 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2d930 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2d940 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2d950 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2d960 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2d970 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
2d980 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d990 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
2d9a0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
2d9b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2d9c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2d9d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2d9e0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
2d9f0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2da00 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
2da10 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
2da20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2da30 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
2da40 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
2da50 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2da60 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
2da70 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2da80 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
2da90 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
2daa0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
2dab0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
2dac0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
2dad0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
2dae0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
2daf0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
2db00 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
2db10 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
2db20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2db30 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2db40 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
2db50 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
2db60 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
2db70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2db80 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2db90 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
2dba0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
2dbb0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
2dbc0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2dbd0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
2dbe0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
2dbf0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2dc00 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
2dc10 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
2dc20 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
2dc30 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2dc40 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2dc50 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
2dc60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
2dc70 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
2dc80 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
2dc90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
2dca0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2dcb0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2dcc0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
2dcd0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
2dce0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
2dcf0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2dd00 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
2dd10 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2dd20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
2dd30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
2dd40 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
2dd50 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
2dd60 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
2dd70 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
2dd80 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
2dd90 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
2dda0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
2ddb0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
2ddc0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
2ddd0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
2dde0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2ddf0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
2de00 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
2de10 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
2de20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
2de30 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
2de40 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
2de50 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
2de60 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
2de70 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
2de80 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2de90 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
2dea0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
2deb0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
2dec0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
2ded0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
2dee0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
2def0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
2df00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2df10 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2df20 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
2df30 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2df40 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
2df50 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
2df60 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
2df70 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
2df80 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
2df90 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2dfa0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
2dfb0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2dfc0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
2dfd0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
2dfe0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
2dff0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
2e000 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
2e010 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
2e020 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
2e030 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
2e040 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
2e050 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
2e060 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
2e070 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2e080 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
2e090 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
2e0a0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
2e0b0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
2e0c0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
2e0d0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
2e0e0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
2e0f0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
2e100 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
2e110 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
2e120 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
2e130 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
2e140 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2e150 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2e160 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
2e170 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
2e180 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
2e190 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
2e1a0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
2e1b0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
2e1c0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
2e1d0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2e1e0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
2e1f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2e200 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
2e210 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
2e220 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
2e230 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
2e240 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
2e250 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2e260 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
2e270 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2e280 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
2e290 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2e2a0 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
2e2b0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2e2c0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
2e2d0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
2e2e0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
2e2f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2e300 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
2e310 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
2e320 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
2e330 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
2e340 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
2e350 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2e360 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2e370 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
2e380 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
2e390 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2e3a0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
2e3b0 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
2e3c0 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
2e3d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
2e3e0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
2e3f0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
2e400 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
2e410 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2e420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
2e430 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
2e440 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
2e450 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
2e460 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
2e470 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
2e480 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2e490 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
2e4a0 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
2e4b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2e4c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
2e4d0 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
2e4e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2e4f0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
2e500 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
2e510 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
2e520 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
2e530 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
2e540 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2e550 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
2e560 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2e570 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
2e580 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2e590 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
2e5a0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
2e5b0 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
2e5c0 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
2e5d0 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
2e5e0 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
2e5f0 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
2e600 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
2e610 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2e620 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
2e630 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
2e640 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
2e650 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
2e660 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
2e670 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
2e680 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
2e690 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
2e6a0 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
2e6b0 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
2e6c0 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
2e6d0 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
2e6e0 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
2e6f0 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
2e700 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
2e710 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
2e720 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2e730 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
2e740 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
2e750 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
2e760 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
2e770 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
2e780 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
2e790 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2e7a0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
2e7b0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
2e7c0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
2e7d0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
2e7e0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2e7f0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
2e800 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
2e810 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
2e820 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
2e830 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
2e840 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
2e850 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2e860 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e870 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
2e880 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
2e890 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
2e8a0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
2e8b0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
2e8c0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
2e8d0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
2e8e0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
2e8f0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
2e900 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
2e910 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
2e920 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
2e930 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
2e940 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
2e950 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
2e960 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2e970 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2e980 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e990 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
2e9a0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
2e9b0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2e9c0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2e9d0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2e9e0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
2e9f0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
2ea00 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2ea10 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
2ea20 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
2ea30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2ea40 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2ea50 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2ea60 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
2ea70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2ea80 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2ea90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
2eaa0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2eab0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2eac0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2ead0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
2eae0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2eaf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2eb00 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2eb10 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2eb20 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2eb30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2eb40 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2eb50 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2eb60 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2eb70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2eb80 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2eb90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2eba0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2ebb0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2ebc0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2ebd0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2ebe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2ebf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ec00 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2ec10 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2ec20 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2ec30 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2ec40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2ec50 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2ec60 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2ec70 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2ec80 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2ec90 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2eca0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2ecb0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2ecc0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2ecd0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2ece0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2ecf0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2ed00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2ed10 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2ed20 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2ed30 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2ed40 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2ed50 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2ed60 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2ed70 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2ed80 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2ed90 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2eda0 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2edb0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2edc0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2edd0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2ede0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2edf0 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2ee00 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2ee10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2ee20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ee30 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
2ee40 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2ee50 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2ee60 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
2ee70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2ee80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2ee90 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2eea0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2eeb0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2eec0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2eed0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2eee0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2eef0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2ef00 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2ef10 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2ef20 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2ef30 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2ef40 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2ef50 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2ef60 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2ef70 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2ef80 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2ef90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2efa0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2efb0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2efc0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2efd0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2efe0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2eff0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2f000 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2f010 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2f020 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2f030 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2f040 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2f050 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2f060 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2f070 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2f080 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2f090 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2f0a0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2f0b0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2f0c0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2f0d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2f0e0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2f0f0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2f100 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2f110 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2f120 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2f130 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2f140 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2f150 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2f160 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2f170 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2f180 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2f190 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2f1a0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2f1b0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2f1c0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2f1d0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
2f1e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f1f0 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  mt.**.** These r
2f200 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2f210 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2f220 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2f230 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2f240 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2f250 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2f260 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2f270 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2f280 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2f290 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2f2a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2f2b0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2f2c0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2f2d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f2e0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2f2f0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2f300 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2f310 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2f320 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2f330 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2f340 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2f350 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2f360 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2f370 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2f380 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2f390 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2f3a0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2f3b0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2f3c0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2f3d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2f3e0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2f3f0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2f400 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2f410 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2f420 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2f430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2f440 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2f450 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2f460 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2f470 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2f480 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2f490 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2f4a0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2f4b0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2f4c0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2f4d0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2f4e0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2f4f0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2f500 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2f510 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2f520 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2f530 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2f540 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2f550 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2f560 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2f570 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2f580 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2f590 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2f5a0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2f5b0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2f5c0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2f5d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2f5e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2f5f0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2f600 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2f610 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2f620 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2f630 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2f640 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2f650 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2f660 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2f670 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2f680 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2f690 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2f6a0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2f6b0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2f6c0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2f6d0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2f6e0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2f6f0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2f700 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2f710 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2f720 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f730 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2f740 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2f750 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2f760 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2f770 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2f780 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2f790 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2f7a0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2f7b0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2f7c0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2f7d0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2f7e0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2f7f0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2f800 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2f810 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2f820 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2f830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f840 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2f850 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2f860 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2f870 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2f880 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2f890 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2f8a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2f8b0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2f8c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2f8d0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2f8e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2f8f0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2f900 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2f910 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2f920 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2f930 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2f940 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2f950 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2f960 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f970 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2f980 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2f990 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2f9a0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2f9b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2f9c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f9d0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2f9e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2f9f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2fa00 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2fa10 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2fa20 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2fa30 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2fa40 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2fa50 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2fa60 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2fa70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2fa80 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2fa90 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2faa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fab0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2fac0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2fad0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2fae0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2faf0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2fb00 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2fb10 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2fb20 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2fb30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2fb40 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2fb50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fb60 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2fb70 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2fb80 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2fb90 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2fba0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2fbb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fbc0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2fbd0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2fbe0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2fbf0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2fc00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2fc10 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2fc20 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2fc30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fc40 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2fc50 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2fc60 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2fc70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2fc80 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2fc90 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2fca0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2fcb0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2fcc0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2fcd0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2fce0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2fcf0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2fd00 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2fd10 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2fd20 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2fd30 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2fd40 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2fd50 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2fd60 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2fd70 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2fd80 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2fd90 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2fda0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2fdb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fdc0 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2fdd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fde0 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2fdf0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2fe00 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2fe10 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2fe20 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2fe30 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2fe40 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2fe50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2fe60 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2fe70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fe80 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2fe90 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2fea0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2feb0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2fec0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2fed0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2fee0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2fef0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ff00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2ff10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2ff20 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2ff30 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2ff40 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2ff50 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2ff60 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2ff70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2ff80 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2ff90 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2ffa0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2ffb0 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2ffc0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ffd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2ffe0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2fff0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30000 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30010 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
30020 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
30030 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
30040 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
30050 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
30060 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
30070 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
30080 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
30090 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
300a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
300b0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
300c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
300d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
300e0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
300f0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
30100 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
30110 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
30120 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
30130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30140 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
30150 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
30160 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
30170 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
30180 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
30190 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
301a0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
301b0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
301c0 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
301d0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
301e0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
301f0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
30200 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
30210 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
30220 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
30230 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
30240 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
30250 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
30260 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
30270 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
30280 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
30290 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
302a0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
302b0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
302c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
302d0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
302e0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
302f0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
30300 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
30310 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
30320 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
30330 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
30340 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
30350 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
30360 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
30370 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
30380 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
30390 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
303a0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
303b0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
303c0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
303d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
303e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
303f0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
30400 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
30410 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30420 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
30430 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
30440 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
30450 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
30460 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
30470 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
30480 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
30490 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
304a0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
304b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
304c0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
304d0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
304e0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
304f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
30500 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
30510 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
30520 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
30530 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
30540 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
30550 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
30560 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
30570 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
30580 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
30590 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
305a0 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
305b0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
305c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
305d0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
305e0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
305f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
30600 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
30610 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
30620 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
30630 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
30640 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
30650 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
30660 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
30670 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
30680 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
30690 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
306a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
306b0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
306c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
306d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
306e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
306f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
30700 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
30710 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
30720 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
30730 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
30740 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
30750 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
30760 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
30770 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
30780 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
30790 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
307a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
307b0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
307c0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
307d0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
307e0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
307f0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
30800 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
30810 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
30820 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
30830 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
30840 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
30850 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
30860 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
30870 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
30880 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
30890 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
308a0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
308b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
308c0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
308d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
308e0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
308f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30900 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
30910 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
30920 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
30930 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
30940 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
30950 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
30960 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
30970 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
30980 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
30990 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
309a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
309b0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
309c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
309d0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
309e0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
309f0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
30a00 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
30a10 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
30a20 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
30a30 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
30a40 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
30a50 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
30a60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
30a70 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
30a80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30a90 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
30aa0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
30ab0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
30ac0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
30ad0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
30ae0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
30af0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
30b00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
30b10 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
30b20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
30b30 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
30b40 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
30b50 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
30b60 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
30b70 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
30b80 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
30b90 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
30ba0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
30bb0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
30bc0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
30bd0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
30be0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
30bf0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
30c00 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
30c10 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
30c20 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
30c30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
30c40 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
30c50 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
30c60 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
30c70 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
30c80 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
30c90 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
30ca0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
30cb0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
30cc0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
30cd0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
30ce0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
30cf0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
30d00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
30d10 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
30d20 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
30d30 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
30d40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
30d50 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
30d60 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
30d70 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
30d80 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
30d90 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
30da0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30db0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
30dc0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
30dd0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
30de0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
30df0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30e00 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
30e10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30e20 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
30e30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
30e40 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
30e50 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
30e60 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
30e70 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
30e80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30e90 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
30ea0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
30eb0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
30ec0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
30ed0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
30ee0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
30ef0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
30f00 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
30f10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30f20 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
30f30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30f40 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
30f50 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
30f60 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
30f70 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
30f80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30f90 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
30fa0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
30fb0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
30fc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30fd0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
30fe0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
30ff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31000 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
31010 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
31020 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
31030 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
31040 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
31050 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
31060 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
31070 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
31080 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
31090 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
310a0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
310b0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
310c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
310d0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
310e0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
310f0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
31100 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
31110 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
31120 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
31130 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
31140 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
31150 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
31160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31170 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
31180 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
31190 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
311a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
311b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
311c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
311d0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
311e0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
311f0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
31200 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
31210 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
31220 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
31230 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
31240 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
31250 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
31260 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
31270 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
31280 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
31290 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
312a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
312b0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
312c0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
312d0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
312e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
312f0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
31300 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
31310 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
31320 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31330 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31340 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
31350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31360 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
31370 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
31380 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
31390 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
313a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
313b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
313c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
313d0 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53  ITE_API double S
313e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
313f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
31400 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
31410 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
31420 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
31430 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
31440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
31450 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31460 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
31470 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
31480 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
31490 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
314a0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
314b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
314c0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
314d0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
314e0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
314f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
31500 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
31510 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
31520 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
31530 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
31540 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
31550 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
31560 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31570 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
31580 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
31590 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
315a0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
315b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
315c0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
315d0 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f  3_value *SQLITE_
315e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
315f0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
31600 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31610 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
31620 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
31630 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
31640 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
31650 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
31660 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
31670 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
31680 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
31690 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
316a0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
316b0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
316c0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
316d0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
316e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
316f0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
31700 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
31710 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
31720 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
31730 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
31740 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
31750 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
31760 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
31770 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
31780 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
31790 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
317a0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
317b0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
317c0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
317d0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
317e0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
317f0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
31800 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
31810 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
31820 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
31830 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
31840 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
31850 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
31860 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
31870 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
31880 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
31890 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
318a0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
318b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
318c0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
318d0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
318e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
318f0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
31900 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
31910 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
31920 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
31930 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
31940 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
31950 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
31960 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
31970 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
31980 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
31990 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
319a0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
319b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
319c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
319d0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
319e0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
319f0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
31a00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31a10 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
31a20 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
31a30 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
31a40 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
31a50 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
31a60 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
31a70 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
31a80 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
31a90 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
31aa0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
31ab0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
31ac0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
31ad0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
31ae0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
31af0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
31b00 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
31b10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31b20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
31b30 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
31b40 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
31b50 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
31b60 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54  nt Object.** MET
31b70 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
31b80 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
31b90 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
31ba0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
31bb0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
31bc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
31bd0 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
31be0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
31bf0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
31c00 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
31c10 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
31c20 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
31c30 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
31c40 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
31c50 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
31c60 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
31c70 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
31c80 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
31c90 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
31ca0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
31cb0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
31cc0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
31cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
31ce0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
31cf0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
31d00 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
31d10 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
31d20 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
31d30 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
31d40 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
31d50 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
31d60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
31d70 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
31d80 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
31d90 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
31da0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
31db0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
31dc0 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
31dd0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
31de0 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
31df0 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
31e00 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
31e10 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
31e20 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
31e30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
31e40 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
31e50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
31e60 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
31e70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31e80 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
31e90 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
31ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
31eb0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
31ec0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
31ed0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
31ee0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
31ef0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
31f00 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
31f10 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
31f20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
31f30 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
31f40 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
31f50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31f60 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  S..*/.SQLITE_API
31f70 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
31f80 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 65  ALL sqlite3_rese
31f90 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
31fa0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
31fb0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
31fc0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
31fd0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
31fe0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
31ff0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
32000 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
32010 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
32020 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
32030 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
32040 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
32050 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
32060 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
32070 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
32080 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
32090 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
320a0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
320b0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
320c0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
320d0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
320e0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
320f0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
32100 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
32110 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
32120 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
32130 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
32140 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
32150 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
32160 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
32170 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
32180 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
32190 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
321a0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
321b0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
321c0 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
321d0 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
321e0 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
321f0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
32200 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
32210 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
32220 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
32230 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
32240 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
32250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32260 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
32270 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
32280 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
32290 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
322a0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
322b0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
322c0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
322d0 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
322e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
322f0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
32300 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
32310 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32320 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
32330 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
32340 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
32350 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
32360 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
32370 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
32380 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
32390 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
323a0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
323b0 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
323c0 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
323d0 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
323e0 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
323f0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
32400 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
32410 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
32420 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
32430 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
32440 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
32450 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
32460 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
32470 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
32480 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
32490 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
324a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
324b0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
324c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
324d0 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
324e0 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
324f0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
32500 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
32510 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
32520 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
32530 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
32540 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
32550 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
32560 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
32570 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
32580 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
32590 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
325a0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
325b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
325c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
325d0 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
325e0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
325f0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
32600 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
32610 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
32620 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
32630 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
32640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
32650 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
32660 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
32670 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
32680 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
32690 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
326a0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
326b0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
326c0 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
326d0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
326e0 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
326f0 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
32700 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
32710 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32720 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
32730 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
32740 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
32750 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
32760 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
32770 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
32780 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
32790 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
327a0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
327b0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
327c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
327d0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
327e0 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
327f0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
32800 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
32810 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
32820 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
32830 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
32840 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
32850 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
32860 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
32870 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
32880 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
32890 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
328a0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
328b0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
328c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
328d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
328e0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
328f0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
32900 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
32910 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
32920 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
32930 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
32940 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
32950 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
32960 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
32970 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
32980 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
32990 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
329a0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
329b0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
329c0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
329d0 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
329e0 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
329f0 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
32a00 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
32a10 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
32a20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
32a30 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
32a40 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
32a50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
32a60 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
32a70 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
32a80 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
32a90 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
32aa0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
32ab0 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
32ac0 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
32ad0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
32ae0 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
32af0 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
32b00 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
32b10 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
32b20 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
32b30 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
32b40 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
32b50 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
32b60 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
32b70 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
32b80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32b90 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
32ba0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
32bb0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
32bc0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
32bd0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
32be0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
32bf0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
32c00 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
32c10 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
32c20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
32c30 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
32c40 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
32c50 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
32c60 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
32c70 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32c80 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
32c90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
32ca0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
32cb0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
32cc0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
32cd0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
32ce0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
32cf0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
32d00 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
32d10 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
32d20 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
32d30 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
32d40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32d50 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
32d60 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
32d70 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
32d80 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
32d90 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
32da0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
32db0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
32dc0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
32dd0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
32de0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
32df0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
32e00 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
32e10 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
32e20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32e30 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
32e40 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
32e50 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
32e60 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
32e70 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
32e80 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
32e90 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
32ea0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
32eb0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
32ec0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
32ed0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
32ee0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
32ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32f00 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
32f10 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
32f20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
32f30 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
32f40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32f50 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
32f60 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
32f70 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
32f80 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
32f90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
32fa0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
32fb0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
32fc0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
32fd0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
32fe0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32ff0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
33000 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
33010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
33020 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33030 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
33040 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
33050 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
33060 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
33070 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
33080 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
33090 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
330a0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
330b0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
330c0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
330d0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
330e0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
330f0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
33100 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
33110 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
33120 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
33130 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
33140 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
33150 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
33160 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
33170 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
33180 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
33190 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
331a0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
331b0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
331c0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
331d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
331e0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
331f0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
33200 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
33210 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
33220 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
33230 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
33240 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
33250 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
33260 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
33270 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
33280 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
33290 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
332a0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
332b0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
332c0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
332d0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
332e0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
332f0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
33300 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
33310 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
33320 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
33330 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
33340 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
33350 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
33360 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
33370 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33380 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
33390 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
333a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
333b0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
333c0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
333d0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
333e0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
333f0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
33400 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
33410 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
33420 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
33430 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
33440 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
33450 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
33460 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
33470 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
33480 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
33490 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
334a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
334b0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
334c0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
334d0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
334e0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
334f0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
33500 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
33510 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
33520 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
33530 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
33540 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
33550 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33560 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33570 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33580 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
33590 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
335a0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
335b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
335c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
335d0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
335e0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
335f0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
33600 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
33610 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
33620 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
33630 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
33640 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33650 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
33660 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
33670 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
33680 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
33690 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
336a0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
336b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
336c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
336d0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
336e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
336f0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
33700 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
33710 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
33720 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
33730 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
33740 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
33750 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
33760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33770 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33780 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33790 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
337a0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
337b0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
337c0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
337d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
337e0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
337f0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
33800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
33810 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
33820 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
33830 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
33840 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
33850 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
33860 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
33870 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
33880 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
33890 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
338a0 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20             1    
338b0 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d  /* IMP: R-37514-
338c0 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65  35566 */.#define
338d0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
338e0 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49         2    /* I
338f0 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33  MP: R-03371-3763
33900 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  7 */.#define SQL
33910 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
33920 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20     3    /* IMP: 
33930 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f  R-51971-34154 */
33940 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33950 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
33960 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
33970 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
33980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
33990 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
339a0 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64     /* Deprecated
339b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
339c0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
339d0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
339e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
339f0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
33a00 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
33a10 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  tion Flags.**.**
33a20 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
33a30 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67   may be ORed tog
33a40 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a  ether with the .
33a50 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
33a60 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  | preferred text
33a70 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68   encoding] as th
33a80 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
33a90 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
33aa0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33ab0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
33ac0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33ad0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
33ae0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33af0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65  on_v2()]..*/.#de
33b00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45  fine SQLITE_DETE
33b10 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38  RMINISTIC    0x8
33b20 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
33b30 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
33b40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
33b50 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
33b60 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
33b70 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
33b80 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
33b90 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
33ba0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
33bb0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
33bc0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
33bd0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
33be0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
33bf0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
33c00 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
33c10 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
33c20 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
33c30 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72  ions.  To encour
33c40 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  age programmers 
33c50 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73  to avoid.** thes
33c60 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
33c70 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e  will not explain
33c80 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
33c90 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
33ca0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
33cb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
33cc0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
33cd0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
33ce0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33cf0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
33d00 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
33d10 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
33d20 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
33d30 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33d40 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
33d50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
33d60 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
33d70 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c  PRECATED int SQL
33d80 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33d90 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
33da0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
33db0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
33dc0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
33dd0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
33de0 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  D int SQLITE_STD
33df0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f  CALL sqlite3_glo
33e00 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
33e10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
33e20 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33e30 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
33e40 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 65  ALL sqlite3_thre
33e50 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
33e60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
33e70 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
33e80 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
33e90 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  L sqlite3_memory
33ea0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
33eb0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
33ec0 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20  64,int),.       
33ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
33ee0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
33ef0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
33f00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
33f10 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
33f20 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
33f30 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
33f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
33f50 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
33f60 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
33f70 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
33f80 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
33f90 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
33fa0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
33fb0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
33fc0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
33fd0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
33fe0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
33ff0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
34000 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
34010 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
34020 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
34030 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
34040 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
34050 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34060 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
34070 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34080 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
34090 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
340a0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
340b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
340c0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
340d0 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
340e0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
340f0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
34100 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
34110 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
34120 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34130 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
34140 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
34150 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
34160 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
34170 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
34180 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
34190 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
341a0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
341b0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
341c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
341d0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
341e0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
341f0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
34200 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34210 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
34220 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
34230 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
34240 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
34250 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34260 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
34270 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
34280 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
34290 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
342a0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
342b0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
342c0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
342d0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
342e0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  * except that th
342f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
34300 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
34310 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34320 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
34330 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
34340 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
34350 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
34360 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
34370 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
34380 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
34390 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
343a0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
343b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
343c0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
343d0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
343e0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
343f0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
34400 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
34410 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
34420 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
34430 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
34440 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
34450 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
34460 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
34470 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
34480 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
34490 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
344a0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
344b0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
344c0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
344d0 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
344e0 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
344f0 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
34500 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
34510 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
34520 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
34530 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
34540 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
34550 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
34560 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
34570 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
34580 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
34590 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
345a0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
345b0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
345c0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
345d0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
345e0 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
345f0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
34600 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
34610 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
34620 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
34630 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
34640 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
34650 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
34660 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
34670 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
34680 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
34690 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
346a0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
346b0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
346c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
346d0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
346e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
346f0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
34700 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
34710 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
34720 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
34730 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
34740 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34750 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
34760 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
34770 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
34780 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34790 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
347a0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
347b0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
347c0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
347d0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
347e0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
347f0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
34800 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
34810 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
34820 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
34830 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34840 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
34850 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34860 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
34870 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34880 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
34890 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
348a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
348b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
348c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
348d0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
348e0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
348f0 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45  PI double SQLITE
34900 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34910 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
34920 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34930 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34940 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34950 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
34960 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34970 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
34980 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  e3_int64 SQLITE_
34990 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
349a0 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
349b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
349c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
349d0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c  signed char *SQL
349e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
349f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
34a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34a10 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
34a20 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
34a30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
34a40 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
34a50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34a60 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
34a70 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
34a80 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34a90 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
34aa0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
34ab0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
34ac0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
34ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34ae0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
34af0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
34b00 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
34b10 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
34b20 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
34b30 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
34b40 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
34b50 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34b60 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
34b70 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
34b80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34b90 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
34ba0 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
34bb0 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44  ontext.** METHOD
34bc0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
34bd0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
34be0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
34bf0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
34c00 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
34c10 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
34c20 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
34c30 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
34c40 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
34c50 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
34c60 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34c70 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
34c80 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
34c90 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
34ca0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
34cb0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
34cc0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
34cd0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
34ce0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
34cf0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
34d00 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
34d10 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
34d20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
34d30 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
34d40 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
34d50 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
34d60 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
34d70 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
34d80 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
34d90 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
34da0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
34db0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34dc0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
34dd0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
34de0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
34df0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
34e00 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
34e10 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
34e20 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
34e30 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
34e40 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
34e50 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
34e60 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
34e70 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
34e80 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
34e90 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
34ea0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
34eb0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
34ec0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
34ed0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
34ee0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
34ef0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
34f00 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34f10 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
34f20 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
34f30 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
34f40 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
34f50 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
34f60 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
34f70 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
34f80 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
34f90 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
34fa0 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74  r .** when first
34fb0 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20   called if N is 
34fc0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
34fd0 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
34fe0 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c   a memory.** all
34ff0 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
35000 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
35010 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
35020 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
35030 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35040 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
35050 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
35060 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
35070 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
35080 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
35090 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
350a0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
350b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
350c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
350d0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
350e0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
350f0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
35100 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
35110 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
35120 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
35130 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78  )^  Within the x
35140 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20  Final callback, 
35150 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20  it is customary 
35160 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e  to set.** N=0 in
35170 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
35180 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35190 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74  ext(C,N) so that
351a0 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73   no .** pointles
351b0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
351c0 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a  ions occur..**.*
351d0 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
351e0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
351f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
35200 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
35210 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35220 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
35230 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
35240 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
35250 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
35260 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
35270 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
35280 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
35290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
352a0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
352b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
352c0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
352d0 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
352e0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
352f0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
35300 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
35310 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
35320 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
35330 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
35340 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
35350 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
35360 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
35370 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
35380 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35390 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
353a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67  CALL sqlite3_agg
353b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
353c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
353d0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
353e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
353f0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
35400 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
35410 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
35420 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
35430 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
35440 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35450 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
35460 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
35470 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
35480 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
35490 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
354a0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
354b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
354c0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
354d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
354e0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
354f0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
35500 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
35510 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
35520 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
35530 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
35540 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
35550 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
35560 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
35570 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
35580 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35590 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
355a0 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
355b0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
355c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
355d0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
355e0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
355f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
35600 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
35610 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
35620 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
35630 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
35640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
35650 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
35660 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35670 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
35680 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
35690 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
356a0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
356b0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
356c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
356d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
356e0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
356f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35700 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
35710 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
35720 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
35730 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35740 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35750 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35760 73 71 6c 69 74 65 33 20 2a 53 51 4c 49 54 45 5f  sqlite3 *SQLITE_
35770 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
35780 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
35790 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
357a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
357b0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
357c0 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
357d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
357e0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
357f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d  hese functions m
35800 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e  ay be used by (n
35810 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51  on-aggregate) SQ
35820 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
35830 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
35840 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
35850 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
35860 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
35870 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
35880 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
35890 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
358a0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
358b0 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
358c0 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
358d0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
358e0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
358f0 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
35900 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61  eserved.  An exa
35910 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65  mple.** of where
35920 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75   this might be u
35930 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65  seful is in a re
35940 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
35950 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e   matching.** fun
35960 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
35970 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
35980 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
35990 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f  ssion can be sto
359a0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
359b0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
359c0 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  th the pattern s
359d0 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e  tring.  .** Then
359e0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
359f0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72  pattern string r
35a00 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c  emains the same,
35a10 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  .** the compiled
35a20 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
35a30 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
35a40 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
35a50 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
35a60 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
35a70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
35a80 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
35a90 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
35aa0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35ab0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
35ac0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
35ad0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
35ae0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
35af0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
35b00 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
35b10 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
35b20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35b30 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72  nction. ^If ther
35b40 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
35b50 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
35b60 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ith the function
35b70 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20   argument, this 
35b80 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
35b90 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ata() interface.
35ba0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ** returns a NUL
35bb0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
35bc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
35bd0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
35be0 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  X) interface sav
35bf0 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61  es P as metadata
35c00 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
35c10 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
35c20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35c30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
35c40 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63  ^Subsequent.** c
35c50 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
35c60 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29  get_auxdata(C,N)
35c70 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74   return P from t
35c80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
35c90 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
35ca0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63  xdata(C,N,P,X) c
35cb0 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64  all if the metad
35cc0 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c  ata is still val
35cd0 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66  id or.** NULL if
35ce0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61   the metadata ha
35cf0 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64  s been discarded
35d00 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68  ..** ^After each
35d10 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
35d20 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
35d30 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73  ,P,X) where X is
35d40 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51   not NULL,.** SQ
35d50 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
35d60 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35d70 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20  function X with 
35d80 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63  parameter P exac
35d90 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65  tly.** once, whe
35da0 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  n the metadata i
35db0 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  s discarded..** 
35dc0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
35dd0 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65  o discard the me
35de0 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69  tadata at any ti
35df0 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c  me, including: <
35e00 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e  ul>.** <li> when
35e10 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
35e20 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
35e30 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f  meter changes, o
35e40 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b  r.** <li> when [
35e50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
35e60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
35e70 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
35e80 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ed for the.**   
35e90 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74     SQL statement
35ea0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
35eb0 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  n sqlite3_set_au
35ec0 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b  xdata() is invok
35ed0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20  ed again on the 
35ee0 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  same parameter, 
35ef0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e  or.** <li> durin
35f00 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  g the original s
35f10 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35f20 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61  ta() call when a
35f30 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20   memory .**     
35f40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
35f50 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29  r occurs. </ul>)
35f60 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65  ^.**.** Note the
35f70 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20   last bullet in 
35f80 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65  particular.  The
35f90 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e   destructor X in
35fa0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74   .** sqlite3_set
35fb0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
35fc0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
35fd0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  d immediately, b
35fe0 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c  efore the.** sql
35ff0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
36000 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65  () interface eve
36010 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63  n returns.  Henc
36020 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
36030 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c  xdata().** shoul
36040 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72  d be called near
36050 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
36060 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
36070 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a  ntation and the.
36080 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ** function impl
36090 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
360a0 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75  d not make any u
360b0 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a  se of P after.**
360c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
360d0 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20  data() has been 
360e0 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  called..**.** ^(
360f0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
36100 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
36110 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
36120 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
36130 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
36140 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f  ters that are co
36150 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74  mpile-time const
36160 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ants, including 
36170 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
36180 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
36190 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f  s] and expressio
361a0 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d  ns composed from
361b0 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a   the same.)^.**.
361c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
361d0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
361e0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
361f0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
36200 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
36210 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
36220 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
36230 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
36240 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  L sqlite3_get_au
36250 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
36260 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
36270 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36280 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
36290 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
362a0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
362b0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
362c0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
362d0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
362e0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
362f0 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
36300 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
36310 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
36320 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
36330 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
36340 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
36350 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
36360 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
36370 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
36380 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
36390 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
363a0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
363b0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
363c0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
363d0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
363e0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
363f0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
36400 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
36410 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
36420 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
36430 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
36440 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
36450 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
36460 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
36470 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
36480 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
36490 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
364a0 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
364b0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
364c0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
364d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
364e0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
364f0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
36500 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
36510 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
36520 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
36530 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
36540 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
36550 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
36560 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
36570 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
36580 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
36590 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
365a0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
365b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
365c0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
365d0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
365e0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
365f0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
36600 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
36610 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
36620 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36630 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
36640 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
36650 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
36660 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
36670 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
36680 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
36690 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
366a0 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
366b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
366c0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
366d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
366e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
366f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
36700 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
36710 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
36720 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
36730 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
36740 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
36750 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
36760 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
36770 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
36780 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
36790 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
367a0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
367b0 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
367c0 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
367d0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
367e0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
367f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36800 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
36810 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36820 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
36830 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
36840 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36850 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
36860 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
36870 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
36880 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
36890 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
368a0 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
368b0 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
368c0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
368d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
368e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
368f0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
36900 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
36910 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
36920 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36930 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
36940 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
36950 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
36960 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
36970 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
36980 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
36990 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
369a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
369b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
369c0 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
369d0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
369e0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
369f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36a00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36a10 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
36a20 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
36a30 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
36a40 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
36a50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36a60 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
36a70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36a80 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
36a90 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
36aa0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
36ab0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
36ac0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
36ad0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
36ae0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
36af0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
36b00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
36b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36b20 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
36b30 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36b40 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
36b50 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
36b60 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
36b70 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
36b80 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
36b90 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
36ba0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36bb0 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
36bc0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
36bd0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
36be0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
36bf0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
36c00 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
36c10 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
36c20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
36c30 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
36c40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36c50 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
36c60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
36c70 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
36c80 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
36c90 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
36ca0 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
36cb0 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
36cc0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
36cd0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
36ce0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
36cf0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
36d00 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
36d10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36d20 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
36d30 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
36d40 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
36d50 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
36d60 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
36d70 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
36d80 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
36d90 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
36da0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36db0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
36dc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36dd0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
36de0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
36df0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
36e00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
36e10 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
36e20 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
36e30 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
36e40 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
36e50 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
36e60 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
36e70 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
36e80 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
36e90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36ea0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
36eb0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
36ec0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
36ed0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
36ee0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
36ef0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
36f00 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
36f10 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
36f20 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
36f30 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
36f40 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
36f50 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
36f60 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
36f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36f80 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
36f90 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
36fa0 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
36fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36fc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36fd0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
36fe0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
36ff0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
37000 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
37010 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
37020 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
37030 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
37040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37050 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37060 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
37070 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
37080 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
37090 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
370a0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
370b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
370c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
370d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
370e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
370f0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
37100 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
37110 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37120 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37130 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
37140 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
37150 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
37160 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
37170 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37180 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
37190 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
371a0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
371b0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
371c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
371d0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
371e0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
371f0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
37200 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
37210 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
37220 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37230 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
37240 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
37250 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
37260 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37270 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37280 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
37290 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
372a0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
372b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
372c0 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
372d0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
372e0 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
372f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
37300 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
37310 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
37320 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
37330 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37340 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
37350 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
37360 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
37370 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
37380 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
37390 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
373a0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
373b0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
373c0 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
373d0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73  ively..** ^The s
373e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
373f0 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  xt64() interface
37400 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
37410 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20   value of an.** 
37420 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37430 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
37440 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  be a text string
37450 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a   in an encoding.
37460 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ** specified by 
37470 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c  the fifth (and l
37480 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20  ast) parameter, 
37490 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e  which must be on
374a0 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f  e.** of [SQLITE_
374b0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
374c0 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
374d0 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
374e0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a  ITE_UTF16LE]..**
374f0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
37500 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
37510 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
37520 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
37530 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
37540 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
37550 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
37560 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
37570 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
37580 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
37590 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
375a0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
375b0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
375c0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
375d0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
375e0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
375f0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
37600 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
37610 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
37620 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
37630 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37640 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
37650 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
37660 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
37670 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
37680 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
37690 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
376a0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
376b0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
376c0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
376d0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
376e0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
376f0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
37700 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
37710 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
37720 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
37730 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
37740 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
37750 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
37760 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
37770 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
37780 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
37790 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
377a0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
377b0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
377c0 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
377d0 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
377e0 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
377f0 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
37800 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
37810 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
37820 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
37830 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
37840 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
37850 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
37860 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
37870 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
37880 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
37890 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
378a0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
378b0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
378c0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
378d0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
378e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
378f0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
37900 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
37910 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
37920 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
37930 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
37940 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
37950 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
37960 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
37970 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
37980 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
37990 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
379a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
379b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
379c0 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
379d0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
379e0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
379f0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
37a00 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
37a10 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
37a20 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
37a30 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
37a40 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
37a50 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
37a60 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
37a70 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
37a80 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
37a90 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
37aa0 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
37ab0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
37ac0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
37ad0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
37ae0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37af0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37b00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
37b10 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
37b20 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
37b30 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
37b40 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
37b50 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
37b60 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
37b70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
37b80 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
37b90 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
37ba0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
37bb0 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
37bc0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
37bd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37be0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
37bf0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
37c00 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
37c10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37c20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
37c30 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
37c40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37c50 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37c60 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
37c70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
37c80 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
37c90 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
37ca0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
37cb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
37cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
37cd0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
37ce0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
37cf0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
37d00 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
37d10 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
37d20 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
37d30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
37d40 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
37d50 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
37d60 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
37d70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37d80 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
37d90 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
37da0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
37db0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37dc0 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
37dd0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
37de0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
37df0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
37e00 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
37e10 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
37e20 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
37e30 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
37e40 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
37e50 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
37e60 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
37e70 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
37e80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37e90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
37ea0 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
37eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
37ec0 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
37ed0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
37ee0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
37ef0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
37f00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
37f10 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
37f20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37f30 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
37f40 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
37f50 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
37f60 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
37f70 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  LL sqlite3_resul
37f80 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  t_blob64(sqlite3
37f90 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20  _context*,const 
37fa0 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20  void*,.         
37fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37fc0 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34    sqlite3_uint64
37fd0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
37fe0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
37ff0 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
38000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38010 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
38020 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
38030 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
38040 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
38050 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38060 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
38070 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
38080 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  ar*, int);.SQLIT
38090 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
380a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
380b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
380c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
380d0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
380e0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
380f0 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
38100 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73  CALL sqlite3_res
38110 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
38120 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38130 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
38140 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
38150 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  LL sqlite3_resul
38160 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
38170 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
38180 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
38190 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
381a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
381b0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
381c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
381d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
381e0 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
381f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38200 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
38210 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  ext*, int);.SQLI
38220 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
38230 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
38240 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
38250 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38260 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
38270 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
38280 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
38290 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
382a0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
382b0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  text*);.SQLITE_A
382c0 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53  PI void SQLITE_S
382d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72  TDCALL sqlite3_r
382e0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
382f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
38300 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
38310 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
38320 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
38330 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
38340 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38350 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt64(sqlite3_con
38360 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
38370 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
38380 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
38390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
383a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
383b0 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
383c0 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ding);.SQLITE_AP
383d0 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
383e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
383f0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
38400 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
38410 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
38420 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
38430 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
38440 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
38450 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
38460 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
38470 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
38480 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
38490 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
384a0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
384b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
384c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
384d0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
384e0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
384f0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
38500 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
38510 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
38520 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65  DCALL sqlite3_re
38530 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
38540 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
38550 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
38560 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
38570 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
38580 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
38590 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
385a0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
385b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
385c0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
385d0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
385e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
385f0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  3.**.** ^These f
38600 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
38610 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
38620 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
38630 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
38640 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
38650 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
38660 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
38670 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
38680 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
38690 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
386a0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
386b0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
386c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
386d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
386e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
386f0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
38700 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
38710 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
38720 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
38730 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
38740 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
38750 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
38760 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
38770 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
38780 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
38790 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
387a0 65 2