/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 1d97dd551627efe9284ec65251cbf862fcb1a96d:


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 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
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 2d 2d 56  RSION_NUMBER --V
10d0: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
10e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
10f0: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1100: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1110: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1120: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1130: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
1140: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1150: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71  ite3_version, sq
1160: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1170: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1180: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1190: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
11a0: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
11b0: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
11c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
11d0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
11e0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
11f0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1200: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
1210: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1220: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1230: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1240: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1250: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1260: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1270: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1280: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1290: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
12a0: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
12b0: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
12c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
12d0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
12e0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
12f0: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75  r, and thus insu
1300: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
1310: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
1320: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1330: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1340: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1350: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1360: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1370: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1380: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1390: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
13a0: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
13b0: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
13c0: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
13d0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
13e0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
13f0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
1400: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
1410: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
1420: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1430: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1440: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1450: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1460: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1470: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1480: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1490: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
14a0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
14b0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
14c0: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
14d0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
14e0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
14f0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1500: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
1510: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
1520: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1530: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1540: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1550: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1560: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1570: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1580: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1590: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
15a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
15b0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
15c0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
15d0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
15e0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
15f0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1600: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
1610: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
1620: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1630: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1640: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1650: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1660: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1670: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1680: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1690: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
16a0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
16b0: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
16c0: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
16d0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
16e0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
16f0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
1700: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
1710: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1720: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1730: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1740: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1750: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1760: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1770: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1780: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1790: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
17a0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
17b0: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
17c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
17d0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
17e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17f0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
1800: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
1810: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
1820: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1830: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1840: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1850: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1860: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1870: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1880: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
18b0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18c0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18d0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
18e0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
18f0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
1900: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
1910: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
1920: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1930: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1940: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1950: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1960: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1970: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1980: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1990: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
19a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
19b0: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
19c0: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
19d0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
19e0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
19f0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1a00: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1a10: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1a20: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1a30: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1a40: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1a50: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1a60: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1a70: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1a80: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1a90: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1aa0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1ab0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ac0: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ad0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1ae0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1af0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1b00: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1b10: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1b20: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1b30: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1b40: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1b50: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1b60: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1b70: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1b80: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1b90: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1ba0: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1bb0: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1bc0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1bd0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1be0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1bf0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1c00: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1c10: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1c20: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1c30: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c40: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1c50: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1c60: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1c70: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1c80: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1c90: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1ca0: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1cb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1cc0: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1cd0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1ce0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1cf0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1d00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1d10: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1d20: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1d30: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d40: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1d50: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1d60: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1d70: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1d80: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1d90: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1da0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1db0: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1dc0: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1dd0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1de0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1df0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1e00: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1e10: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1e20: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1e30: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1e40: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1e50: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1e60: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1e70: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1e80: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1e90: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1ea0: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1eb0: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1ec0: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1ed0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1ee0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1ef0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1f00: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1f10: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1f20: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1f30: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1f40: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1f50: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
1f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
1f70: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1f80: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1f90: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1fa0: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1fb0: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1fc0: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1fd0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1fe0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1ff0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
2000: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2010: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
2020: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2030: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2040: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2050: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2060: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2070: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2080: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2090: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
20a0: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
20b0: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
20c0: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
20d0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
20e0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
20f0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
2100: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
2110: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
2120: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2130: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2150: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2160: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2170: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2180: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2190: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
21a0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
21b0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
21c0: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
21d0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
21e0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
21f0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2200: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2210: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2220: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2230: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2240: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2250: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2260: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2270: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2280: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2290: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
22a0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
22b0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
22c0: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
22d0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
22e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
22f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2300: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2310: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2320: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2330: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2340: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2350: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2360: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2380: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2390: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
23a0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
23b0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
23c0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
23d0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
23e0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
23f0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2400: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2410: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2420: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2430: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2440: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2450: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2460: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2470: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2480: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2490: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
24a0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
24b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
24c0: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
24d0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
24e0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
24f0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
2500: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
2510: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2520: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2530: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2540: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2550: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2560: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2570: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2580: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2590: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
25a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
25b0: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
25c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
25d0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
25e0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
25f0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2600: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
2610: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
2620: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2630: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2640: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2650: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2660: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2670: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2680: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2690: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
26a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
26b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
26c0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
26d0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
26e0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
26f0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2700: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2710: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
2720: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2730: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2740: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2750: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2760: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2770: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2780: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2790: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
27a0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
27b0: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
27c0: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
27d0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
27e0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
27f0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2800: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
2810: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
2820: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2830: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2840: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2850: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2870: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2880: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2890: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28a0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
28b0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
28c0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
28d0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
28e0: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
28f0: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
2900: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
2910: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2920: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2930: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
2940: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
2950: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
2960: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
2970: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2980: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
2990: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
29a0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
29b0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
29c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
29d0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
29e0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
29f0: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
2a00: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
2a10: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
2a20: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
2a30: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
2a40: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
2a50: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
2a60: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
2a70: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
2a80: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
2a90: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
2aa0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
2ab0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ac0: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
2ad0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
2ae0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2af0: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
2b00: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2b10: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
2b20: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72  structors.** for
2b30: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2b40: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73  bject..** ^Calls
2b50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   to sqlite3_clos
2b60: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2b70: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72  close_v2() retur
2b80: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  n [SQLITE_OK] if
2b90: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2ba0: 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63  ] object is succ
2bb0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2bc0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2bd0: 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63  iated.** resourc
2be0: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  es are deallocat
2bf0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
2c00: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2c10: 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61  ction is associa
2c20: 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  ted with unfinal
2c30: 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a  ized prepared.**
2c40: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75   statements or u
2c50: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2c60: 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73  3_backup objects
2c70: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c   then sqlite3_cl
2c80: 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65  ose().** will le
2c90: 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ave the database
2ca0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
2cb0: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
2cc0: 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49  ITE_BUSY]..** ^I
2cd0: 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  f sqlite3_close_
2ce0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  v2() is called w
2cf0: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20  ith unfinalized 
2d00: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d10: 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e  nts.** and/or un
2d20: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2d30: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2d40: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2d50: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2d60: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2d70: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2d80: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2d90: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2da0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2db0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dc0: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2dd0: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2de0: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2df0: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2e00: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2e10: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2e20: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2e30: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2e40: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2e50: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2e60: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2e70: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2e80: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2e90: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2ea0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2eb0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2ec0: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2ed0: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2ee0: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2ef0: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2f00: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2f10: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2f20: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2f30: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2f40: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2f50: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2f60: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2f70: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2f80: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2f90: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2fa0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2fb0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2fc0: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2fd0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2fe0: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2ff0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3000: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
3010: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
3020: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
3030: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
3040: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
3050: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
3060: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
3070: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b  hen it returns [
3080: 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74  SQLITE_OK] and t
3090: 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  he deallocation.
30a0: 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20  ** of resources 
30b0: 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  is deferred unti
30c0: 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  l all [prepared 
30d0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
30e0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20  OB handles],.** 
30f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  and [sqlite3_bac
3100: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65  kup] objects are
3110: 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e   also destroyed.
3120: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73  .**.** ^If an [s
3130: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69  qlite3] object i
3140: 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c  s destroyed whil
3150: 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  e a transaction 
3160: 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20  is open,.** the 
3170: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61  transaction is a
3180: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
3190: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
31a0: 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20  The C parameter 
31b0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
31c0: 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  e(C)] and [sqlit
31d0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a  e3_close_v2(C)].
31e0: 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
31f0: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
3200: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
3210: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
3220: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
3230: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
3240: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
3250: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
3260: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
3270: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
3280: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
3290: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
32a0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73  te3_close() or s
32b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
32c0: 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  ) with a NULL po
32d0: 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  inter.** argumen
32e0: 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  t is a harmless 
32f0: 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71  no-op..*/.int sq
3300: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
3310: 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  te3*);.int sqlit
3320: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3330: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3340: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3350: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3360: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3370: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3380: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3390: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
33a0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
33b0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
33c0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
33d0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
33e0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
33f0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
3400: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
3410: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3420: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3430: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
3440: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3450: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3460: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3470: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3480: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3490: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
34a0: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
34b0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34c0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
34d0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
34e0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
34f0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
3500: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3510: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3520: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3530: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3540: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3550: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3560: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3570: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3580: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3590: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
35a0: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
35b0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
35c0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
35d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35e0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
35f0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
3600: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3610: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3620: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3630: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3640: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3650: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3660: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3670: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3680: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3690: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
36a0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
36b0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
36c0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
36d0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
36e0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36f0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
3700: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3710: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3720: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3730: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3740: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3750: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3760: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3770: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3780: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3790: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
37a0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
37b0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
37c0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
37d0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
37e0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
37f0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3800: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3810: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3820: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3830: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3840: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3850: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3860: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3870: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3880: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3890: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
38a0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
38b0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
38c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38d0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
38e0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
38f0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3900: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3910: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3920: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3930: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3940: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3950: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3960: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3970: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3980: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3990: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
39a0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
39b0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
39c0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
39d0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
39e0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39f0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3a00: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3a10: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3a20: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3a30: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3a40: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3a50: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3a60: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3a70: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3a80: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3a90: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3aa0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3ab0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3ac0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3ad0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3ae0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3af0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3b00: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3b10: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3b20: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3b30: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3b40: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3b50: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3b60: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3b70: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3b80: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3b90: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3ba0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3bb0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3bc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3bd0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3be0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3bf0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3c00: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3c10: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3c20: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3c30: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3c40: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3c50: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3c60: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3c70: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3c80: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3c90: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3ca0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3cb0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3cc0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3cd0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3ce0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3cf0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3d00: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3d10: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3d20: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3d30: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3d40: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3d50: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3d60: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3d70: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3d80: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3d90: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3da0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3db0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3dc0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3dd0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3de0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3df0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3e00: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3e10: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3e20: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3e30: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3e40: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3e50: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3e60: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3e70: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3e80: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3e90: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3ea0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3eb0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3ec0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3ed0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3ee0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ef0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3f00: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3f10: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3f20: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3f30: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f40: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3f50: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
3f60: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
3f70: 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74  ied by.**      t
3f80: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
3f90: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3fa0: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3fb0: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3fc0: 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ng..** <li> The 
3fd0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3fe0: 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20   not modify the 
3ff0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
4000: 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  xt passed into.*
4010: 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70  *      the 2nd p
4020: 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
4030: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
4040: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4050: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4060: 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ul>.*/.int sqli
4070: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69  te3_exec(.  sqli
4080: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
40b0: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
40c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
40f0: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
4100: 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c  d */.  int (*cal
4110: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
4120: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c  ,char**,char**),
4130: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75    /* Callback fu
4140: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
4150: 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72         /* 1st ar
4180: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61  gument to callba
4190: 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65  ck */.  char **e
41a0: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20  rrmsg           
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
41d0: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
41e0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
41f0: 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73  EF: Result Codes
4200: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4210: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
4220: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61  itions}.**.** Ma
4230: 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69  ny SQLite functi
4240: 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e  ons return an in
4250: 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64  teger result cod
4260: 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73  e from the set s
4270: 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20  hown.** here in 
4280: 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74  order to indicat
4290: 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  e success or fai
42a0: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  lure..**.** New 
42b0: 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20  error codes may 
42c0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
42d0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
42e0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  QLite..**.** See
42f0: 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64   also: [extended
4300: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4310: 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65  initions].*/.#de
4320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20  fine SQLITE_OK  
4330: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
4340: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c  Successful resul
4350: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e  t */./* beginnin
4360: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  g-of-error-codes
4370: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4380: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20  TE_ERROR        
4390: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72  1   /* SQL error
43a0: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
43b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
43c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20  SQLITE_INTERNAL 
43d0: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72      2   /* Inter
43e0: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  nal logic error 
43f0: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65  in SQLite */.#de
4400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d  fine SQLITE_PERM
4410: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20           3   /* 
4420: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f  Access permissio
4430: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4440: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
4450: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43          4   /* C
4460: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
4470: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f  requested an abo
4480: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  rt */.#define SQ
4490: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20  LITE_BUSY       
44a0: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74    5   /* The dat
44b0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f  abase file is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
44d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20  SQLITE_LOCKED   
44e0: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62      6   /* A tab
44f0: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  le in the databa
4500: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  se is locked */.
4510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4520: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20  OMEM        7   
4530: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61  /* A malloc() fa
4540: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  iled */.#define 
4550: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
4560: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d      8   /* Attem
4570: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65  pt to write a re
4580: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20  adonly database 
4590: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45a0: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39  E_INTERRUPT    9
45b0: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
45c0: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71  terminated by sq
45d0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
45e0: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )*/.#define SQLI
45f0: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31  TE_IOERR       1
4600: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64  0   /* Some kind
4610: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72   of disk I/O err
4620: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23  or occurred */.#
4630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
4640: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f  RRUPT     11   /
4650: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64  * The database d
4660: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c  isk image is mal
4670: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e  formed */.#defin
4680: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  e SQLITE_NOTFOUN
4690: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b  D    12   /* Unk
46a0: 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73  nown opcode in s
46b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
46c0: 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  rol() */.#define
46d0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
46e0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
46f0: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4700: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4710: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4720: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4730: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4740: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4750: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4770: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
4780: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
4790: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
47a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47b0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
47c0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
47d0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
47e0: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
47f0: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4800: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4810: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4830: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4840: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4850: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4860: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4870: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
4880: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
4890: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
48a0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
48b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
48c0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
48d0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
48e0: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
48f0: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4900: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4910: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4920: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4930: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4940: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4950: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4960: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4970: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4980: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
4990: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
49a0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
49c0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
49d0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
49e0: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
49f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a00: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4a10: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4a20: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4a30: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4a40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a50: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4a60: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4a70: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
4a80: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
4a90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4aa0: 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20  _NOTICE      27 
4ab0: 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f    /* Notificatio
4ac0: 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ns from sqlite3_
4ad0: 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  log() */.#define
4ae0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20   SQLITE_WARNING 
4af0: 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e      28   /* Warn
4b00: 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  ings from sqlite
4b10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69  3_log() */.#defi
4b20: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4b30: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4b40: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4b50: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4b60: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4b70: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4b80: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4b90: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4ba0: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4bb0: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4bc0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4bd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4be0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
4bf0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
4c00: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c10: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4c20: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
4c30: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
4c40: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
4c50: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
4c60: 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67   one of 30 integ
4c70: 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f  er.** [result co
4c80: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20  des].  However, 
4c90: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
4ca0: 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f  hown that many o
4cb0: 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c  f.** these resul
4cc0: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
4cd0: 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  coarse-grained. 
4ce0: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
4cf0: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
4d00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
4d10: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72  t problems as pr
4d20: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
4d30: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66  like.  In an eff
4d40: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73  ort to.** addres
4d50: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65  s this, newer ve
4d60: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4d70: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20   (version 3.3.8 
4d80: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
4d90: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
4da0: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
4db0: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
4dc0: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
4dd0: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
4de0: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
4df0: 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65  . These [extende
4e00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
4e10: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4e20: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
4e30: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
4e40: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
4e50: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
4e60: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
4e70: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
4e80: 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e  .  Or, the exten
4e90: 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20  ded code for.** 
4ea0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
4eb0: 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74  error can be obt
4ec0: 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  ained using.** [
4ed0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
4ee0: 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a  _errcode()]..*/.
4ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4f00: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
4f10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4f20: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
4f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f40: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
4f50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4f60: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ERR | (2<<8)).#d
4f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4f80: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20  RR_WRITE        
4f90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4fa0: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
4fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fc0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4fd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fe0: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
4ff0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5000: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20  _DIR_FSYNC      
5010: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5020: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5030: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5040: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20  TRUNCATE        
5050: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5060: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5070: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
5080: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20  STAT            
5090: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
50a0: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
50b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
50c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
50d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50e0: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
5100: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5110: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5120: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5140: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53  TE            (S
5150: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5160: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5170: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
5180: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53  KED           (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
51a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
51b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
51c0: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  M             (S
51d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
51e0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
51f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45  QLITE_IOERR_ACCE
5200: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53  SS            (S
5210: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5220: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5230: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43  QLITE_IOERR_CHEC
5240: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53  KRESERVEDLOCK (S
5250: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5260: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5270: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b  QLITE_IOERR_LOCK
5280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5290: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52a0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
52b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53  QLITE_IOERR_CLOS
52c0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
52d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52e0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5300: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53  CLOSE         (S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5320: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
5330: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f  QLITE_IOERR_SHMO
5340: 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53  PEN           (S
5350: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5360: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53  QLITE_IOERR_SHMS
5380: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53  IZE           (S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53a0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
53b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c  QLITE_IOERR_SHML
53c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53  OCK           (S
53d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
53e0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
53f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d  QLITE_IOERR_SHMM
5400: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AP            (S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5420: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b  QLITE_IOERR_SEEK
5440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5450: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5460: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5470: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5480: 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53  TE_NOENT      (S
5490: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
54a0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
54b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50  QLITE_IOERR_MMAP
54c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
54d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
54e0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
54f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54  QLITE_IOERR_GETT
5500: 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53  EMPPATH       (S
5510: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5520: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5530: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56  QLITE_IOERR_CONV
5540: 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53  PATH          (S
5550: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5560: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5570: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41  QLITE_LOCKED_SHA
5580: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53  REDCACHE      (S
5590: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20  QLITE_LOCKED |  
55a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f  SQLITE_BUSY_RECO
55c0: 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28  VERY           (
55d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
55e0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
55f0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41   SQLITE_BUSY_SNA
5600: 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20  PSHOT           
5610: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5620: 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (2<<8)).#defin
5630: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5640: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
5650: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5660: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
5670: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5680: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
5690: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
56a0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
56b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
56c0: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
56d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
56e0: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
56f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5700: 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48  ANTOPEN_CONVPATH
5710: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5720: 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29  ANTOPEN | (4<<8)
5730: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5740: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
5750: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5760: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
5770: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5780: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5790: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
57a0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
57b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
57c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
57d0: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
57e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57f0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5800: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5810: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53  OLLBACK       (S
5820: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5830: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5840: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5850: 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20  _DBMOVED        
5860: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5870: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5880: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f  ne SQLITE_ABORT_
5890: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20  ROLLBACK        
58a0: 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20    (SQLITE_ABORT 
58b0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
58c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
58d0: 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20  INT_CHECK       
58e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
58f0: 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  INT | (1<<8)).#d
5900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5910: 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f  STRAINT_COMMITHO
5920: 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  OK   (SQLITE_CON
5930: 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29  STRAINT | (2<<8)
5940: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5950: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45  _CONSTRAINT_FORE
5960: 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45  IGNKEY   (SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33  _CONSTRAINT | (3
5980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5990: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59a0: 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51  FUNCTION     (SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59c0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
59d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
59e0: 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20  INT_NOTNULL     
59f0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a00: 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  INT | (5<<8)).#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a20: 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b  STRAINT_PRIMARYK
5a30: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5a40: 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29  STRAINT | (6<<8)
5a50: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a60: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47  _CONSTRAINT_TRIG
5a70: 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  GER      (SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37  _CONSTRAINT | (7
5a90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5aa0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ab0: 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51  UNIQUE       (SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5ad0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
5ae0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5af0: 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  INT_VTAB        
5b00: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b10: 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  INT | (9<<8)).#d
5b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b30: 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20  STRAINT_ROWID   
5b40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b50: 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29  STRAINT |(10<<8)
5b60: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b70: 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f  _NOTICE_RECOVER_
5b80: 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45  WAL      (SQLITE
5b90: 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29  _NOTICE | (1<<8)
5ba0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5bb0: 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f  _NOTICE_RECOVER_
5bc0: 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45  ROLLBACK (SQLITE
5bd0: 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29  _NOTICE | (2<<8)
5be0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5bf0: 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44  _WARNING_AUTOIND
5c00: 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  EX       (SQLITE
5c10: 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38  _WARNING | (1<<8
5c20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c30: 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20  E_AUTH_USER     
5c40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5c50: 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29  E_AUTH | (1<<8))
5c60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5c70: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5c80: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5c90: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5ca0: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5cb0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5cc0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5cd0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5ce0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5cf0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5d00: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5d10: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5d20: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5d30: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d50: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5d60: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5d70: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d80: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5da0: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5db0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5dc0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5dd0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5de0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5df0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5e00: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5e10: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5e20: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5e30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e40: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5e50: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5e60: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e80: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5e90: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5ea0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ec0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5ed0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5ee0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ef0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f00: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5f10: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
5f20: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f30: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f50: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
5f60: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
5f70: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f80: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fa0: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5fb0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
5fc0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fe0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
5ff0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
6000: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6010: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6020: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
6030: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
6040: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6050: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6060: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
6070: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
6080: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6090: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
60a0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
60b0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
60c0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
60d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
60e0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
60f0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
6100: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6110: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6120: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
6130: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
6140: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
6150: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6160: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
6170: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
6180: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6190: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
61a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
61b0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
61c0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
61d0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
61e0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
61f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6200: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
6210: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6220: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6230: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6240: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6250: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
6260: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
6270: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6280: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6290: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
62a0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
62b0: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
62c0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
62d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
62e0: 46 49 4c 45 50 52 4f 54 45 43 54 49 4f 4e 5f 4d  FILEPROTECTION_M
62f0: 41 53 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  ASK             
6300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6310: 20 20 20 20 30 78 30 30 37 30 30 30 30 30 0a 0a      0x00700000..
6320: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
6330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6340: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
6350: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
6360: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
6370: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
6380: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6390: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
63a0: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
63b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
63c0: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
63d0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
63e0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
63f0: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
6400: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
6410: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
6420: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
6430: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
6440: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
6450: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
6460: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6470: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
6480: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6490: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
64a0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
64b0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
64c0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
64d0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
64e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
64f0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
6500: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6510: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6520: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
6530: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
6540: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
6550: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6560: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6570: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6580: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6590: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
65a0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
65b0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
65c0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
65d0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
65e0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
65f0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
6600: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6610: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6620: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
6630: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
6640: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6650: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6660: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6670: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6680: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6690: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
66a0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
66b0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
66c0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
66d0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
66e0: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
66f0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
6700: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
6710: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
6720: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
6730: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
6740: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
6750: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
6760: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
6770: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
6780: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
6790: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
67a0: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
67b0: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
67c0: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
67d0: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
67e0: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ged.  The SQLITE
67f0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6800: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20  LE_WHEN_OPEN.** 
6810: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68  flag indicate th
6820: 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74  at a file cannot
6830: 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e   be deleted when
6840: 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53   open.  The.** S
6850: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6860: 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63  TABLE flag indic
6870: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69  ates that the fi
6880: 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64  le is on.** read
6890: 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20  -only media and 
68a0: 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
68b0: 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73  d even by proces
68c0: 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76  ses with.** elev
68d0: 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e  ated privileges.
68e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
68f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6910: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
6920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6930: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
6940: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6950: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6960: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
6970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6980: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
6990: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
69a0: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
69b0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
69c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
69d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
69e0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
69f0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
6a00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6a10: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
6a20: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
6a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6a40: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
6a50: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a60: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
6a70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a80: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
6a90: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
6aa0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6ab0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
6ac0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
6ad0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6ae0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6af0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
6b00: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
6b10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6b20: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
6b30: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
6b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b50: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6b60: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
6b70: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
6b80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6b90: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6ba0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23      0x00001000.#
6bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6bc0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20  CAP_IMMUTABLE   
6bd0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6be0: 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  02000../*.** CAP
6bf0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
6c00: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
6c10: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
6c20: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
6c30: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6c40: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
6c50: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
6c60: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
6c70: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
6c80: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
6c90: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
6ca0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
6cb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6cc0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
6cd0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
6ce0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6cf0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
6d00: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
6d10: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
6d20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d30: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
6d40: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
6d50: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
6d60: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
6d70: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
6d80: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
6d90: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
6da0: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
6db0: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
6dc0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
6dd0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6de0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
6df0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
6e00: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
6e10: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
6e20: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
6e30: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
6e40: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6e50: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
6e60: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
6e70: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
6e80: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
6e90: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
6ea0: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
6eb0: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
6ec0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
6ed0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
6ee0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6ef0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
6f00: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
6f10: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
6f20: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
6f30: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
6f40: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
6f50: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
6f60: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
6f70: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
6f80: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
6f90: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6fa0: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
6fb0: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
6fc0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
6fd0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
6fe0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
6ff0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
7000: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
7010: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7020: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7030: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7040: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7050: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
7060: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
7070: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
7080: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
7090: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
70a0: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
70b0: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
70c0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
70d0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
70e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
70f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7100: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
7110: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7120: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7130: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7140: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7150: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
7160: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
7170: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
7180: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
7190: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
71a0: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
71b0: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
71c0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
71d0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
71e0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
71f0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
7200: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
7210: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7220: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7230: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7240: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7250: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
7260: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
7270: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
7280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7290: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
72a0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
72b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
72c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
72d0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
72e0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
72f0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
7300: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7310: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7320: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7330: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7340: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7350: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
7360: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
7370: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
7380: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
7390: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
73a0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
73b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
73c0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
73d0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
73e0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
73f0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7400: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
7410: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7420: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7430: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7440: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7450: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
7460: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
7470: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
7480: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
7490: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
74a0: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
74b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
74c0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
74d0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
74e0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
74f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7500: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7510: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7520: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7530: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7540: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7550: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
7560: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
7570: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
7580: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
7590: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
75a0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
75b0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
75c0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
75d0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
75e0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
75f0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
7600: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7610: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7620: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7630: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7640: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7650: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
7660: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
7670: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
7680: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
7690: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
76a0: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
76b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
76c0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
76d0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
76e0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
76f0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
7700: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7710: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7720: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7730: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7740: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7750: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
7760: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
7770: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
7780: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
7790: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
77a0: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
77b0: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
77c0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
77d0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
77e0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
77f0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
7800: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7810: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7820: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7830: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7840: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7850: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7860: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7870: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7880: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7890: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
78a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
78b0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
78c0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
78d0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
78e0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
78f0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
7900: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7910: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7920: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7930: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7940: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7950: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7960: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7970: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7980: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7990: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
79a0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
79b0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
79c0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
79d0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
79e0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
79f0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
7a00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7a10: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7a20: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
7a30: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
7a40: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
7a50: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
7a60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
7a70: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
7a80: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
7a90: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
7aa0: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
7ab0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
7ac0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
7ad0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
7ae0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
7af0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
7b00: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
7b10: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
7b20: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
7b30: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
7b40: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
7b50: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
7b60: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
7b70: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
7b80: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
7b90: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
7ba0: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
7bb0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
7bc0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
7bd0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
7be0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
7bf0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
7c00: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
7c10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
7c20: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
7c30: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
7c40: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
7c50: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
7c60: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
7c70: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
7c80: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
7c90: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
7ca0: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
7cb0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
7cc0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
7cd0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
7ce0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
7cf0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
7d00: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
7d10: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
7d20: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
7d30: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
7d40: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
7d50: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
7d60: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
7d70: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
7d80: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
7d90: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
7da0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
7db0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
7dc0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
7dd0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
7de0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
7df0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
7e00: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
7e10: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
7e20: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
7e30: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
7e40: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
7e50: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
7e60: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
7e70: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
7e80: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
7e90: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
7ea0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
7eb0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
7ec0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
7ed0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
7ee0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
7ef0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
7f00: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
7f10: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
7f20: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
7f30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
7f40: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
7f50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
7f60: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
7f70: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
7f80: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
7f90: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
7fa0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
7fb0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
7fc0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
7fd0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
7fe0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
7ff0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
8000: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
8010: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
8020: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
8030: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
8040: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
8050: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
8060: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
8070: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8080: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
8090: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
80a0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
80b0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
80c0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
80d0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
80e0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
80f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
8100: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8110: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8120: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8130: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8140: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8150: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8160: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8170: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8180: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8190: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
81a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
81b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
81c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
81d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
81e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
81f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8200: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8210: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8220: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8230: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8240: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
8250: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8260: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8270: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8280: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8290: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
82a0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
82b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
82c0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
82d0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
82e0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
82f0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8300: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8310: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8320: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8330: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8340: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8350: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8360: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8370: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8380: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8390: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
83a0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
83b0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
83c0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
83d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
83e0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
83f0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8400: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8410: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8420: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8430: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8440: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8450: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8460: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8470: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8480: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8490: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
84a0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
84b0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
84c0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
84d0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
84e0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
84f0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8500: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8510: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8520: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8530: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8540: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8550: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8560: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8570: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8580: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8590: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
85a0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
85b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
85c0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
85d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
85e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
85f0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8600: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8610: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8620: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8630: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8640: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8650: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8660: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8670: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8680: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8690: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
86a0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
86b0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
86c0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
86d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
86e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
86f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8700: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8710: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8720: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8740: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8750: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8760: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8770: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8780: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8790: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
87a0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
87b0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
87c0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
87d0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
87e0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
87f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8800: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8810: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8820: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8830: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8840: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8850: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8860: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8870: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8880: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8890: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
88a0: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
88b0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
88c0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
88d0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
88e0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
88f0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8900: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8910: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8920: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
8930: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
8940: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8950: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
8960: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
8970: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
8980: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8990: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
89a0: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
89b0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
89c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
89d0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
89e0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
89f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
8a00: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8a10: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8a20: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
8a30: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8a40: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8a50: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
8a60: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
8a70: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
8a80: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
8a90: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
8aa0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
8ab0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
8ac0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20  trol Opcodes.** 
8ad0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20  KEYWORDS: {file 
8ae0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d  control opcodes}
8af0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8b00: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  pcode}.**.** The
8b10: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
8b20: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
8b30: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
8b40: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
8b50: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
8b60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
8b70: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
8b80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8b90: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
8ba0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  face..**.** <ul>
8bb0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8bc0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8bd0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8be0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8bf0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8c00: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8c10: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8c20: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8c30: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8c40: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8c50: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8c60: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8c70: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8c80: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8c90: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8ca0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8cb0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8cc0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8cd0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8ce0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8cf0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8d00: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
8d10: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
8d20: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
8d30: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
8d40: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20   testing and is 
8d50: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77  only available w
8d60: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hen the SQLITE_T
8d70: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  EST.** compile-t
8d80: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ime option is us
8d90: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
8da0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8db0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
8dc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8dd0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8de0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8df0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8e00: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8e10: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8e20: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8e30: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8e40: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
8e50: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
8e60: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
8e70: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
8e80: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
8e90: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
8ea0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8eb0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
8ec0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
8ed0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8ee0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8ef0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8f00: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8f10: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8f20: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8f30: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
8f40: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8f50: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8f60: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
8f70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8f80: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
8f90: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8fa0: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8fb0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
8fc0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
8fd0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8fe0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8ff0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
9000: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
9010: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
9020: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9030: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
9040: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
9050: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
9060: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
9070: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
9080: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
9090: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
90a0: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
90b0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
90c0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
90d0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
90e0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
90f0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
9100: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
9110: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
9120: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
9130: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
9140: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9150: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
9160: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
9170: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9180: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9190: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
91a0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
91b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
91c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
91d0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
91e0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
91f0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
9200: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
9210: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9220: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
9230: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
9240: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
9250: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9260: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9270: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9280: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9290: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
92a0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
92b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
92c0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
92d0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
92e0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
92f0: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9300: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9310: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
9320: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
9330: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
9340: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
9350: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
9360: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9370: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9380: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9390: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
93a0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
93b0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
93c0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
93d0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
93e0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
93f0: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9400: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9410: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
9420: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
9430: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
9440: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
9450: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
9460: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
9470: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9480: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9490: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
94a0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
94b0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
94c0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
94d0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
94e0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
94f0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
9500: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
9510: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
9520: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
9530: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9540: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
9550: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9560: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
9570: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
9580: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
9590: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
95a0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
95b0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
95c0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
95d0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
95e0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
95f0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9600: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9610: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9620: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9630: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
9640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9650: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
9660: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
9670: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
9680: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
9690: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
96a0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
96b0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
96c0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
96d0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
96e0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
96f0: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
9700: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
9710: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
9720: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9730: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9740: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
9750: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
9760: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9770: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9780: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9790: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
97a0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
97b0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
97c0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
97d0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
97e0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
97f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9800: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
9810: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9820: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9830: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
9840: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
9850: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
9860: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
9870: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
9880: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
9890: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
98a0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
98b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
98c0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
98d0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
98e0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
98f0: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
9900: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
9910: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
9920: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
9930: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
9940: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
9950: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
9960: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
9970: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
9980: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
9990: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
99a0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
99b0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
99c0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
99d0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
99e0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
99f0: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
9a00: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
9a10: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
9a20: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
9a30: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
9a40: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
9a50: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
9a60: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
9a70: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
9a80: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
9a90: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
9aa0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
9ab0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
9ac0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
9ad0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
9ae0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
9af0: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
9b00: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65  integer i the ne
9b10: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
9b20: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
9b30: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
9b40: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
9b50: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
9b60: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
9b70: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
9b80: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
9b90: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
9ba0: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
9bb0: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
9bc0: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
9bd0: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
9be0: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
9bf0: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
9c00: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
9c10: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
9c20: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
9c30: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
9c40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9c50: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
9c60: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9c70: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9c80: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9c90: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
9ca0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
9cb0: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
9cc0: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
9cd0: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
9ce0: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
9cf0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
9d00: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
9d10: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
9d20: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
9d30: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
9d40: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
9d50: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
9d60: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
9d70: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9d80: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
9d90: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
9da0: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
9db0: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
9dc0: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
9dd0: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
9de0: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
9df0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
9e00: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
9e10: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
9e20: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
9e30: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
9e40: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
9e50: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
9e60: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
9e70: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
9e80: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
9e90: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9ea0: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
9eb0: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
9ec0: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
9ed0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
9ee0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9ef0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
9f00: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
9f10: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
9f20: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
9f30: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
9f40: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
9f50: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
9f60: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
9f70: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
9f80: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
9f90: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
9fa0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
9fb0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
9fc0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
9fd0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
9fe0: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
9ff0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a000: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a010: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a020: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a040: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a050: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a060: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a070: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a080: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
a090: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
a0a0: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
a0b0: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
a0c0: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
a0d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
a0e0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a0f0: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
a100: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
a110: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
a120: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
a130: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
a140: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a150: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
a160: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
a170: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a180: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a190: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a1a0: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
a1b0: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
a1c0: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
a1d0: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
a1e0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
a1f0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
a200: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
a210: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
a220: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a230: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a240: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a250: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
a260: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a270: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
a280: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
a290: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
a2a0: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
a2b0: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
a2c0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
a2d0: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
a2e0: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
a2f0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
a300: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
a310: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
a320: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
a330: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
a340: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
a350: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
a360: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
a370: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a380: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a390: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a3a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a3b0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
a3c0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
a3d0: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
a3e0: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
a3f0: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
a400: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
a410: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
a420: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
a430: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
a440: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
a450: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
a460: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
a470: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
a480: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
a490: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
a4a0: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
a4b0: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
a4c0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
a4d0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a4e0: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
a4f0: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
a500: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
a510: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
a520: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
a530: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
a540: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
a550: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
a560: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
a570: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
a580: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
a590: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
a5a0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
a5b0: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
a5c0: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
a5d0: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
a5e0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
a5f0: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
a600: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
a610: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
a620: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
a630: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
a640: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a650: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
a660: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
a670: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
a680: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
a690: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a6a0: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
a6b0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
a6c0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
a6d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
a6e0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
a6f0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
a700: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
a710: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
a720: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
a730: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
a740: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a750: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a760: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
a770: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
a780: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
a790: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
a7a0: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
a7b0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
a7c0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
a7d0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
a7e0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
a7f0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a800: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
a810: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
a820: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
a830: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
a840: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
a850: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
a860: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a870: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
a880: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
a890: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
a8a0: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
a8b0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
a8c0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
a8d0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
a8e0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
a8f0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
a900: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
a910: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
a920: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
a930: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
a940: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
a950: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
a960: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
a970: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a980: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a990: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
a9a0: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
a9b0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
a9c0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
a9d0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
a9e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a9f0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
aa00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
aa10: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
aa20: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
aa30: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
aa40: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
aa50: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
aa60: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
aa70: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
aa80: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
aa90: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
aaa0: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
aab0: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
aac0: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
aad0: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
aae0: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
aaf0: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
ab00: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
ab10: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
ab20: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ab30: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
ab40: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
ab50: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
ab60: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
ab70: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
ab80: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
ab90: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
aba0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
abb0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
abc0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
abd0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
abe0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
abf0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
ac00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ac10: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
ac20: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
ac30: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
ac40: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
ac50: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
ac60: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
ac70: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
ac80: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
ac90: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
aca0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
acb0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
acc0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
acd0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
ace0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
acf0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
ad00: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
ad10: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
ad20: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
ad30: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
ad40: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
ad50: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
ad60: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
ad70: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
ad80: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
ad90: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
ada0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
adb0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
adc0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
add0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
ade0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
adf0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
ae00: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
ae10: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
ae20: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
ae30: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
ae40: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
ae50: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
ae60: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
ae70: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
ae80: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
ae90: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
aea0: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
aeb0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
aec0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
aed0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
aee0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
aef0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
af00: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
af10: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
af20: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
af30: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
af40: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
af50: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
af60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
af70: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
af80: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
af90: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
afa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
afb0: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
afc0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
afd0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
afe0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
aff0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
b000: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
b010: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
b020: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
b030: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b040: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
b050: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
b060: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
b070: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
b080: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
b090: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
b0a0: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
b0b0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
b0c0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
b0d0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
b0e0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b0f0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
b100: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
b110: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
b120: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
b130: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
b140: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
b150: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b160: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
b170: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b180: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
b190: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b1a0: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
b1b0: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
b1c0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b1d0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
b1e0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
b1f0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
b200: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
b210: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
b220: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
b230: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
b240: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
b250: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b260: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
b270: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
b280: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
b290: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
b2a0: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
b2b0: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
b2c0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
b2d0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
b2e0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
b2f0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
b300: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
b310: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
b320: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
b330: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
b340: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
b350: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
b360: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
b370: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
b380: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
b390: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
b3a0: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
b3b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b3c0: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
b3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b3e0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b3f0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
b400: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
b410: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
b420: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
b430: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
b440: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
b450: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
b460: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b470: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
b480: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
b490: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
b4a0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b4b0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
b4c0: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
b4d0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
b4e0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
b4f0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
b500: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
b510: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
b520: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
b530: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
b540: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
b550: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
b560: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b570: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b580: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b590: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b5a0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
b5b0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
b5c0: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
b5d0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
b5e0: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
b5f0: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
b600: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
b610: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
b620: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
b630: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
b640: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
b650: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
b660: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
b670: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
b680: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b690: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b6a0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
b6b0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b6c0: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
b6d0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
b6e0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
b6f0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
b700: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
b710: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
b720: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
b730: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
b740: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
b750: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
b760: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
b770: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
b780: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
b790: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
b7a0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
b7b0: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
b7c0: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
b7d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b7e0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
b7f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b800: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
b810: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
b820: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
b830: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
b840: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
b850: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
b860: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
b870: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
b880: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
b890: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
b8a0: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
b8b0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
b8c0: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
b8d0: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
b8e0: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
b8f0: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
b900: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
b910: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
b920: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
b930: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
b940: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 2f  ontrol..**.** </
b950: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
b960: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
b970: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
b980: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
b990: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
b9a0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
b9b0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
b9c0: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
b9d0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b9e0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
b9f0: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
ba00: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
ba10: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
ba20: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
ba30: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
ba40: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
ba50: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
ba60: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
ba70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ba80: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
ba90: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
baa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bab0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
bac0: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
bad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bae0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
baf0: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
bb00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bb10: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
bb20: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
bb30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bb40: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
bb50: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
bb60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bb70: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
bb80: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
bb90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bba0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
bbb0: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
bbc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
bbd0: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
bbe0: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
bbf0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
bc00: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
bc10: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
bc20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
bc30: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
bc40: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
bc50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
bc60: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
bc70: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
bc80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
bc90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bca0: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
bcb0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
bcc0: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
bcd0: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
bce0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
bcf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bd00: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
bd10: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
bd20: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
bd30: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
bd40: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
bd50: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33  _HANDLE       23
bd60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bd70: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20  FCNTL_WAL_BLOCK 
bd80: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a               24.
bd90: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
bda0: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
bdb0: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
bdc0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bdd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
bde0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
bdf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
be00: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
be10: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
be20: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
be30: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
be40: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
be50: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
be60: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
be70: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
be80: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
be90: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
bea0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
beb0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
bec0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
bed0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
bee0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
bef0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
bf00: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
bf10: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
bf20: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
bf30: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
bf40: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
bf50: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
bf60: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
bf70: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
bf80: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
bf90: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
bfa0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
bfb0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
bfc0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
bfd0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
bfe0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
bff0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c000: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c010: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
c020: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
c030: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c040: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c050: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c060: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
c070: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
c080: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
c090: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
c0a0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
c0b0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
c0c0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
c0d0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
c0e0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
c0f0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
c100: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
c110: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
c120: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
c130: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
c140: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
c150: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
c160: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
c170: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
c180: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
c190: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
c1a0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
c1b0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
c1c0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
c1d0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
c1e0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
c1f0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
c200: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
c210: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c220: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
c230: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
c240: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
c250: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
c260: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
c270: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c280: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
c290: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
c2a0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
c2b0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c2c0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
c2d0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
c2e0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
c2f0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
c300: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
c310: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
c320: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
c330: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
c340: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
c350: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
c360: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
c370: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
c380: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
c390: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
c3a0: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
c3b0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
c3c0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
c3d0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
c3e0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
c3f0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
c400: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
c410: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c420: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
c430: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
c440: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
c450: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c460: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
c470: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
c480: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
c490: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c4a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
c4b0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
c4c0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
c4d0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c4e0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
c4f0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
c500: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
c510: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
c520: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
c530: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
c540: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
c550: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
c560: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c570: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c580: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
c590: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
c5a0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
c5b0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
c5c0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
c5d0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
c5e0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
c5f0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
c600: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
c610: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
c620: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
c630: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
c640: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
c650: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
c660: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
c670: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
c680: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c690: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
c6a0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
c6b0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
c6c0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
c6d0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
c6e0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
c6f0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
c700: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
c710: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
c720: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c730: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
c740: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
c750: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
c760: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
c770: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
c780: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
c790: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
c7a0: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
c7b0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
c7c0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
c7d0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
c7e0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
c7f0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
c800: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
c810: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
c820: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
c830: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
c840: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
c850: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
c860: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
c870: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
c880: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
c890: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
c8a0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
c8b0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
c8c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
c8d0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
c8e0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
c8f0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
c900: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
c910: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
c920: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
c930: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
c940: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
c950: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
c960: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
c970: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
c980: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
c990: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
c9a0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
c9b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
c9c0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
c9d0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
c9e0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
c9f0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
ca00: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
ca10: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
ca20: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
ca30: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
ca40: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
ca50: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
ca60: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
ca70: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
ca80: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
ca90: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
caa0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
cab0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
cac0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
cad0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
cae0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
caf0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cb00: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
cb10: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
cb20: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
cb30: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
cb40: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
cb50: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cb60: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
cb70: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
cb80: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
cb90: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
cba0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
cbb0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
cbc0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
cbd0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cbe0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
cbf0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cc00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
cc10: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
cc20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
cc30: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
cc40: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
cc50: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
cc60: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cc70: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
cc80: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cc90: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
cca0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ccb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
ccc0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
ccd0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
cce0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
ccf0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
cd00: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
cd10: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
cd20: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
cd30: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
cd40: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
cd50: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
cd60: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
cd70: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
cd80: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
cd90: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
cda0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
cdb0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
cdc0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
cdd0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
cde0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
cdf0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
ce00: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
ce10: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
ce20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
ce30: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
ce40: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
ce50: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
ce60: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
ce70: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
ce80: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
ce90: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
cea0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
ceb0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
cec0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
ced0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
cee0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
cef0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
cf00: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
cf10: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
cf20: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
cf30: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
cf40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
cf50: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
cf60: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
cf70: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
cf80: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
cf90: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cfa0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
cfb0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
cfc0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
cfd0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
cfe0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
cff0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d000: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d010: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
d020: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
d030: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
d040: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
d050: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
d060: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
d070: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
d080: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
d090: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
d0a0: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
d0b0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
d0c0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
d0d0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
d0e0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
d0f0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
d100: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
d110: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
d120: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
d130: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
d140: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
d150: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
d160: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
d170: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d180: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
d190: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
d1a0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
d1b0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
d1c0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
d1d0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
d1e0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
d1f0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
d200: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d210: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
d220: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
d230: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
d240: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
d250: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
d260: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
d270: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
d280: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
d290: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
d2a0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
d2b0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
d2c0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
d2d0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
d2e0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
d2f0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
d300: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
d310: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
d320: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
d330: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
d340: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d350: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
d360: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d370: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
d380: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
d390: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d3a0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
d3b0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
d3c0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
d3d0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
d3e0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
d3f0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
d400: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
d410: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
d420: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
d430: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
d440: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
d450: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
d460: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
d470: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
d480: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
d490: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
d4a0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
d4b0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
d4c0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d4d0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
d4e0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
d4f0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
d500: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d510: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
d520: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d530: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
d540: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
d550: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d560: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
d570: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d580: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
d590: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
d5a0: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
d5b0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
d5c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
d5d0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
d5e0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
d5f0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
d600: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
d610: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
d620: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
d630: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
d640: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
d650: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
d660: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
d670: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
d680: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d690: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
d6a0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
d6b0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
d6c0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
d6d0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
d6e0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
d6f0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
d700: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
d710: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
d720: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
d730: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
d740: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
d750: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
d760: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
d770: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d780: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
d790: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
d7a0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
d7b0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
d7c0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
d7d0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
d7e0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
d7f0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
d800: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
d810: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
d820: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
d830: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
d840: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
d850: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
d860: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
d870: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
d880: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
d890: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
d8a0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
d8b0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
d8c0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
d8d0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
d8e0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
d8f0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
d900: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
d910: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
d920: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
d930: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
d940: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
d950: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
d960: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
d970: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
d980: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
d990: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
d9a0: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
d9b0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
d9c0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
d9d0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
d9e0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
d9f0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
da00: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
da10: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
da20: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
da30: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
da40: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
da50: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
da60: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
da70: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
da80: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
da90: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
daa0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
dab0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
dac0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
dad0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
dae0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
daf0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
db00: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
db10: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
db20: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
db30: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
db40: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
db50: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
db60: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
db70: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
db80: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
db90: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
dba0: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
dbb0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
dbc0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
dbd0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
dbe0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
dbf0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
dc00: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
dc10: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
dc20: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
dc30: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
dc40: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
dc50: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
dc60: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
dc70: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
dc80: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
dc90: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
dca0: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
dcb0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
dcc0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
dcd0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
dce0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
dcf0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
dd00: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
dd10: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
dd20: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
dd30: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
dd40: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
dd50: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
dd60: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
dd70: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
dd80: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
dd90: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
dda0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
ddb0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
ddc0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
ddd0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
dde0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
ddf0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
de00: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
de10: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
de20: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
de30: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
de40: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
de50: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
de60: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
de70: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
de80: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
de90: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
dea0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
deb0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
dec0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
ded0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
dee0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
def0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
df00: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
df10: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
df20: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
df30: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
df40: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
df50: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
df60: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
df70: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
df80: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
df90: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
dfa0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
dfb0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
dfc0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
dfd0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
dfe0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
dff0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e000: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e010: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
e020: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
e030: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e040: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
e050: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
e060: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
e070: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
e080: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
e090: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
e0a0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e0b0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e0c0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
e0d0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
e0e0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
e0f0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
e100: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
e110: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e120: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
e130: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
e140: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
e150: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e160: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
e170: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
e180: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
e190: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
e1a0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e1b0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
e1c0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e1d0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
e1e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e1f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
e200: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
e210: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
e220: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e230: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
e240: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
e250: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
e260: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
e270: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
e280: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
e290: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
e2a0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
e2b0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
e2c0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
e2d0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
e2e0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
e2f0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
e300: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
e310: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
e320: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e330: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e340: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
e350: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
e360: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e370: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
e380: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e390: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e3a0: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
e3b0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e3c0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
e3d0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
e3e0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
e3f0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
e400: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
e410: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e420: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
e430: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
e440: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
e450: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e460: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e470: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
e480: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e490: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
e4a0: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
e4b0: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
e4c0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
e4d0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
e4e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e4f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e500: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
e510: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
e520: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
e530: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
e540: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e550: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e560: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
e570: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
e580: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e590: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e5a0: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
e5b0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e5c0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e5d0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
e5e0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e5f0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
e600: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
e610: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
e620: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
e630: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
e640: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
e650: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
e660: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
e670: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
e680: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e690: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
e6a0: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
e6b0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
e6c0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
e6d0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
e6e0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
e6f0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e700: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
e710: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
e720: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
e730: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
e740: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
e750: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
e760: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
e770: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e780: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
e790: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
e7a0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
e7b0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
e7c0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
e7d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e7e0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
e7f0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
e800: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
e810: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
e820: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
e830: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
e840: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
e850: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
e860: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
e870: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
e880: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
e890: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
e8a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e8b0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
e8c0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
e8d0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
e8e0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
e8f0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
e900: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
e910: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
e920: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
e930: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
e940: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e950: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
e960: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
e970: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
e980: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
e990: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
e9a0: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
e9b0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
e9c0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
e9d0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
e9e0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
e9f0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
ea00: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
ea10: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ea20: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
ea30: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ea40: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
ea50: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
ea60: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ea70: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
ea80: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ea90: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
eaa0: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
eab0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
eac0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
ead0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
eae0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
eaf0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
eb00: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
eb10: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
eb20: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
eb30: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
eb40: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
eb50: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
eb60: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
eb70: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
eb80: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
eb90: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
eba0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
ebb0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ebc0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
ebd0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
ebe0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
ebf0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
ec00: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
ec10: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
ec20: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ec30: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ec40: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
ec50: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ec60: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ec70: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
ec80: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
ec90: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
eca0: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
ecb0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
ecc0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
ecd0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
ece0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
ecf0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
ed00: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ed10: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
ed20: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
ed30: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
ed40: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
ed50: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
ed60: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
ed70: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
ed80: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
ed90: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
eda0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
edb0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
edc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
edd0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
ede0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
edf0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
ee00: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
ee10: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ee20: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
ee30: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
ee40: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
ee50: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
ee60: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
ee70: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
ee80: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
ee90: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
eea0: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
eeb0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
eec0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
eed0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
eee0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
eef0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
ef00: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
ef10: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
ef20: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
ef30: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
ef40: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
ef50: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
ef60: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
ef70: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
ef80: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
ef90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
efa0: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
efb0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
efc0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
efd0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
efe0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
eff0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f000: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f010: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
f020: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f030: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
f040: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
f050: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
f060: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
f070: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
f080: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
f090: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
f0a0: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
f0b0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
f0c0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
f0d0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
f0e0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
f0f0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f100: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f110: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f120: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f130: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
f140: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
f150: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f160: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f170: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
f180: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
f190: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
f1a0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
f1b0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
f1c0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
f1d0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
f1e0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
f1f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
f200: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
f210: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
f220: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f230: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
f240: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
f250: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
f260: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
f270: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
f280: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f290: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
f2a0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
f2b0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f2c0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
f2d0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f2e0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
f2f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f300: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
f310: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
f320: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f330: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
f340: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
f350: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
f360: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
f370: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f380: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
f390: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
f3a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
f3b0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
f3c0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
f3d0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
f3e0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
f3f0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
f400: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
f410: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
f420: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
f430: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
f440: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
f450: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f460: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
f470: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
f480: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
f490: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
f4a0: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
f4b0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
f4c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f4d0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
f4e0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
f4f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f500: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
f510: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f520: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
f530: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
f540: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
f550: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
f560: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
f570: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f580: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
f590: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f5a0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
f5b0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
f5c0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
f5d0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
f5e0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
f5f0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
f600: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
f610: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
f620: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
f630: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
f640: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
f650: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
f660: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
f670: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
f680: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f690: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f6a0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
f6b0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
f6c0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
f6d0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
f6e0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
f6f0: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
f700: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
f710: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f720: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f730: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
f740: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
f750: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
f760: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f770: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
f780: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
f790: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
f7a0: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
f7b0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
f7c0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
f7d0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
f7e0: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
f7f0: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
f800: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
f810: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
f820: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
f830: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
f840: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
f850: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
f860: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
f870: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f880: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
f890: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
f8a0: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
f8b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f8c0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
f8d0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
f8e0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
f8f0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
f900: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
f910: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
f920: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
f930: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
f940: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
f950: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
f960: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
f970: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
f980: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
f990: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
f9a0: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
f9b0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
f9c0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
f9d0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
f9e0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
f9f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
fa00: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
fa10: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
fa20: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
fa30: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
fa40: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
fa50: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
fa60: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
fa70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fa80: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
fa90: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
faa0: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
fab0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fac0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
fad0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
fae0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
faf0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
fb00: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
fb10: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
fb20: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
fb30: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
fb40: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
fb50: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
fb60: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
fb70: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
fb80: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
fb90: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
fba0: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
fbb0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
fbc0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
fbd0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
fbe0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
fbf0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
fc00: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
fc10: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
fc20: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
fc30: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
fc40: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
fc50: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fc60: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
fc70: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
fc80: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
fc90: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
fca0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
fcb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
fcc0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
fcd0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
fce0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
fcf0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
fd00: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
fd10: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
fd20: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
fd30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fd40: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
fd50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fd60: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
fd70: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
fd80: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
fd90: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
fda0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
fdb0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
fdc0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
fdd0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
fde0: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
fdf0: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
fe00: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
fe10: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
fe20: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
fe30: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
fe40: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
fe50: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
fe60: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
fe70: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
fe80: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
fe90: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
fea0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
feb0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
fec0: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
fed0: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
fee0: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
fef0: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
ff00: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
ff10: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ff20: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
ff30: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
ff40: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
ff50: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
ff60: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
ff70: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
ff80: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
ff90: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
ffa0: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
ffb0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
ffc0: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
ffd0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
ffe0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
fff0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
10000 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
10010 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10020 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10030 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10040 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10060 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10070 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
10080 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
10090 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
100a0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
100b0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
100c0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
100d0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
100e0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
100f0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
10100 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
10110 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10120 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10130 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10140 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10150 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10160 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10170 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
10180 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10190 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
101a0 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
101b0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
101c0 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
101d0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
101e0 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
101f0 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
10200 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
10210 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
10220 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
10230 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
10240 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
10250 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
10260 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
10270 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
10280 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
10290 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
102a0 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
102b0 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
102c0 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
102d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
102e0 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
102f0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
10300 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
10310 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
10320 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
10330 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
10340 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
10350 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
10360 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
10370 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
10380 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
10390 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
103a0 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
103b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
103c0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
103d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
103e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
103f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10400 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
10410 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
10420 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
10430 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
10440 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
10450 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
10460 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
10470 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
10480 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
10490 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
104a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
104b0 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
104c0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
104d0 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
104e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
104f0 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
10500 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
10510 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
10520 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
10530 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
10540 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
10550 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
10560 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
10570 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
10580 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10590 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
105a0 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
105b0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
105c0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
105d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
105e0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
105f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10600 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
10610 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
10620 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10630 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
10640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
10650 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
10660 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
10670 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10680 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
10690 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
106a0 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
106b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
106c0 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
106d0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
106e0 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
106f0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
10700 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
10710 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
10720 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
10730 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
10740 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
10750 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
10760 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
10770 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
10780 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
10790 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
107a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
107b0 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
107c0 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
107d0 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
107e0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
107f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10800 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
10810 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
10820 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
10830 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
10840 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
10850 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
10860 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
10870 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
10880 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
10890 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
108a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
108b0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
108c0 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
108d0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
108e0 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
108f0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
10900 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
10910 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
10920 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10930 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
10940 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
10950 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
10960 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
10970 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10980 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
10990 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
109a0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
109b0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
109c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
109d0 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
109e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
109f0 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
10a00 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10a10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
10a20 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
10a30 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
10a40 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
10a50 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
10a60 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
10a70 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
10a80 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
10a90 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
10aa0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
10ab0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
10ac0 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
10ad0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
10ae0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10af0 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
10b00 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
10b10 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
10b20 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
10b30 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
10b40 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
10b50 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
10b60 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
10b70 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
10b80 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
10b90 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
10ba0 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
10bb0 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
10bc0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
10bd0 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
10be0 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
10bf0 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
10c00 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
10c10 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
10c20 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
10c30 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
10c40 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
10c50 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
10c60 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
10c70 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
10c80 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
10c90 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
10ca0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
10cb0 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
10cc0 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
10cd0 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
10ce0 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
10cf0 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
10d00 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
10d10 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
10d20 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
10d30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
10d40 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
10d50 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
10d60 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
10d70 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
10d80 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
10d90 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
10da0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
10db0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
10dc0 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
10dd0 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
10de0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
10df0 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
10e00 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
10e10 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
10e20 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
10e30 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
10e40 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
10e50 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
10e60 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
10e70 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
10e80 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
10e90 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
10ea0 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
10eb0 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
10ec0 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
10ed0 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
10ee0 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
10ef0 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
10f00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
10f10 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
10f20 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
10f30 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
10f40 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
10f50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
10f60 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
10f70 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
10f80 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
10f90 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
10fa0 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
10fb0 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
10fc0 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
10fd0 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
10fe0 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
10ff0 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
11000 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
11010 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
11020 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
11030 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
11040 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
11050 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
11060 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
11070 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
11080 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
11090 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
110a0 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
110b0 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
110c0 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
110d0 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
110e0 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
110f0 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
11100 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
11110 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
11120 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
11130 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
11140 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
11150 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
11160 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
11170 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
11180 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
11190 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
111a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
111b0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
111c0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
111d0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
111e0 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
111f0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
11200 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
11210 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
11220 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
11230 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
11240 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
11250 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
11260 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
11270 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
11280 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
11290 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
112a0 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
112b0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
112c0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
112d0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
112e0 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
112f0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
11300 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
11310 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
11320 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
11330 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
11340 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
11350 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
11360 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
11370 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
11380 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11390 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
113a0 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
113b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
113c0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
113d0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
113e0 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
113f0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
11400 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
11410 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
11420 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
11430 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
11440 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
11450 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11460 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
11470 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
11480 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
11490 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
114a0 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
114b0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
114c0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
114d0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
114e0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
114f0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
11500 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
11510 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
11520 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
11530 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
11540 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
11550 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11560 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
11570 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
11580 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
11590 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
115a0 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
115b0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
115c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
115d0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
115e0 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
115f0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
11600 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
11610 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
11620 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
11630 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
11640 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
11650 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
11660 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
11670 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
11680 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
11690 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
116a0 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
116b0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
116c0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
116d0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
116e0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
116f0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
11700 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11710 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
11720 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11730 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
11740 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
11750 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
11760 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11770 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11780 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
11790 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
117a0 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
117b0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
117c0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
117d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
117e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
117f0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
11800 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
11810 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
11820 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
11830 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
11840 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
11850 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
11860 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
11870 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
11880 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
11890 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
118a0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
118b0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
118c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
118d0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
118e0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
118f0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
11900 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
11910 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
11920 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
11930 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
11940 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
11950 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
11960 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
11970 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
11980 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
11990 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
119a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
119b0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
119c0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
119d0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
119e0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
119f0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
11a00 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
11a10 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
11a20 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
11a30 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
11a40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11a50 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
11a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11a70 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
11a80 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
11a90 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
11aa0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
11ab0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11ac0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
11ad0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
11ae0 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
11af0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
11b00 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
11b10 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
11b20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
11b30 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
11b40 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
11b50 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
11b60 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
11b70 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11b80 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11b90 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11ba0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11bb0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11bc0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11bd0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11be0 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
11bf0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11c00 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
11c10 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
11c20 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
11c30 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
11c40 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
11c50 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
11c60 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11c70 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
11c80 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11c90 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
11ca0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11cb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11cc0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11cd0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
11ce0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11cf0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11d00 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11d10 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11d20 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11d30 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11d40 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11d50 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
11d60 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
11d70 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
11d80 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
11d90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11da0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11db0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11dc0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
11dd0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
11de0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
11df0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
11e00 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
11e10 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11e20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11e30 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
11e40 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
11e50 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
11e60 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
11e70 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
11e80 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
11e90 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
11ea0 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
11eb0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
11ec0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
11ed0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11ee0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
11ef0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
11f00 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11f10 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11f20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11f30 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11f40 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11f50 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11f60 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
11f70 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
11f80 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
11f90 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11fa0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11fb0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11fc0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11fd0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11fe0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12000 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
12010 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
12020 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12030 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12040 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
12050 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
12060 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
12070 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
12080 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
12090 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
120a0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
120b0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
120c0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
120d0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
120e0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
120f0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
12100 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
12110 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
12120 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
12130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
12140 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12150 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
12160 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
12170 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
12180 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
12190 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
121a0 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
121b0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
121c0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
121d0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
121e0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
121f0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
12200 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
12210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12220 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
12230 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
12240 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
12250 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
12260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
12270 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
12280 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12290 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
122a0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
122b0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
122c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
122d0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
122e0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
122f0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
12300 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
12310 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
12320 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
12330 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
12340 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
12350 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12360 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
12370 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
12380 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12390 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
123a0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
123b0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
123c0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
123d0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
123e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
123f0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
12400 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12410 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12420 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
12430 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
12440 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12450 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12460 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
12470 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12480 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12490 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
124a0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
124b0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
124c0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
124d0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
124e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
124f0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12500 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
12510 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
12520 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12530 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
12540 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
12550 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
12560 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
12570 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
12580 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12590 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
125a0 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
125b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
125c0 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
125d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
125e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
125f0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12600 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12610 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
12620 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
12630 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
12640 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12650 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12660 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
12670 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12680 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12690 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
126a0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
126b0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
126c0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
126d0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
126e0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
126f0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
12700 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12710 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
12720 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
12730 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
12740 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
12750 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
12760 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
12770 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
12780 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
12790 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
127a0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
127b0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
127c0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
127d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
127e0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
127f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12800 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
12810 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
12820 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12830 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
12840 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
12850 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
12860 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
12870 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
12880 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
12890 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
128a0 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
128b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
128c0 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
128d0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
128e0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
128f0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
12900 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
12910 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12920 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
12930 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
12940 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
12950 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
12960 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
12970 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12980 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
12990 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
129a0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
129b0 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
129c0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
129d0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
129e0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
129f0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12a00 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
12a10 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
12a20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
12a30 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
12a40 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
12a50 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
12a60 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
12a70 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12a80 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
12a90 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
12aa0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12ac0 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
12ad0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12ae0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
12af0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12b00 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
12b10 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12b20 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12b30 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
12b40 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
12b50 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
12b60 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
12b70 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
12b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12b90 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
12ba0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
12bb0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
12bc0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
12bd0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
12be0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
12bf0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
12c00 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
12c10 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
12c20 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
12c30 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
12c40 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12c50 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
12c60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12c70 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
12c80 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
12c90 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
12ca0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
12cb0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
12cc0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
12cd0 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
12ce0 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
12cf0 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
12d00 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
12d10 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
12d20 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
12d30 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
12d40 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
12d50 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
12d60 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
12d70 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
12d80 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
12d90 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
12da0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
12db0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
12dc0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
12dd0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
12de0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12df0 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
12e00 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
12e10 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
12e20 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
12e30 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
12e40 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
12e50 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
12e60 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
12e70 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
12e80 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
12e90 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
12ea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
12eb0 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
12ec0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
12ed0 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
12ee0 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
12ef0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12f00 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
12f10 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
12f20 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
12f30 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
12f40 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
12f50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12f60 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
12f70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12f80 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
12f90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
12fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
12fb0 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
12fc0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12fd0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
12fe0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
12ff0 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61  n use for the da
13000 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
13010 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
13020 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  lt page.** cache
13030 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13040 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
13050 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
13060 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
13070 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
13080 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
13090 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
130a0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
130b0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
130c0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a  NFIG_PCACHE2].**
130d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
130e0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65  ption..** ^There
130f0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
13100 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
13110 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a  ONFIG_PAGECACHE:
13120 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   A pointer to.**
13130 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
13140 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
13150 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
13160 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
13170 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
13180 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
13190 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
131a0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
131b0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
131c0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
131d0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
131e0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
131f0 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d   65536) plus som
13200 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f  e extra bytes fo
13210 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
13220 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d  eader.  ^The num
13230 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74  ber of extra byt
13240 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65  es needed by the
13250 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20   page header.** 
13260 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
13270 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
13280 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13290 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20  E_HDRSZ] option 
132a0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
132b0 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49  config()]..** ^I
132c0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
132d0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
132e0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
132f0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
13300 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
13310 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
13320 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
13330 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
13340 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
13350 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f  byte aligned blo
13360 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61  ck of memory tha
13370 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73 74  t.** is at least
13380 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
13390 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73 65  emory, otherwise
133a0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
133b0 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
133c0 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ined..** ^SQLite
133d0 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
133e0 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
133f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13400 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
13410 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
13420 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
13430 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
13440 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
13450 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
13460 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
13470 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
13480 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
13490 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
134a0 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
134b0 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
134c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
134d0 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
134e0 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
134f0 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
13500 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13510 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
13520 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
13530 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
13540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13550 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
13560 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
13570 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61  y buffer .** tha
13580 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
13590 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
135a0 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
135b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
135c0 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  .** beyond those
135d0 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79   provided for by
135e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
135f0 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20  SCRATCH] and.** 
13600 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13610 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54  AGECACHE]..** ^T
13620 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13630 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20  _HEAP option is 
13640 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
13650 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13660 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74  iled.** with eit
13670 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
13680 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b  LE_MEMSYS3] or [
13690 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
136a0 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72  MSYS5] and retur
136b0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  ns.** [SQLITE_ER
136c0 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20  ROR] if invoked 
136d0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54  otherwise..** ^T
136e0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
136f0 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
13700 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a  TE_CONFIG_HEAP:.
13710 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  ** An 8-byte ali
13720 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
13730 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
13740 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
13750 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
13760 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
13770 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
13780 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
13790 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
137a0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
137b0 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
137c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
137d0 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
137e0 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
137f0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
13800 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
13810 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
13820 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
13830 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
13840 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
13850 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
13860 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
13870 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
13880 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61   NULL then the a
13890 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
138a0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
138b0 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
138c0 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
138d0 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
138e0 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
138f0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
13900 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
13910 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
13920 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
13930 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
13940 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
13950 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
13960 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
13970 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
13980 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
13990 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
139a0 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
139b0 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
139c0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
139d0 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
139e0 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
139f0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13a00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13a10 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
13a20 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
13a30 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
13a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13a50 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
13a60 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13a70 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a  nt which is a.**
13a80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
13a90 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
13aa0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13ab0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13ac0 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
13ad0 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65  t specifies alte
13ae0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
13af0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
13b00 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69   to be used.** i
13b10 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65  n place the mute
13b20 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
13b30 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
13b40 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
13b50 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
13b60 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
13b70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13b80 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13b90 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
13ba0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13bb0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
13bc0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
13bd0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13be0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13bf0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13c00 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13c10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13c20 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
13c30 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
13c40 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
13c50 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
13c60 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
13c70 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
13c80 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13c90 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13ca0 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
13cb0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
13cc0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
13cd0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
13ce0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13cf0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13d00 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
13d10 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
13d20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13d30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13d40 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  GETMUTEX option 
13d50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13d60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
13d70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13d80 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
13d90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
13da0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
13db0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
13dc0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13dd0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
13de0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
13df0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13e00 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
13e10 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
13e20 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
13e30 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
13e40 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
13e50 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
13e60 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
13e70 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
13e80 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
13e90 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
13ea0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
13eb0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
13ec0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
13ed0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13ee0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13ef0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13f00 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13f10 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13f20 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13f30 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13f40 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13f50 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13f60 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
13f70 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
13f80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13f90 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
13fa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13fb0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
13fc0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
13fd0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
13fe0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
13ff0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14000 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
14010 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14020 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
14030 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
14040 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14050 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74  OKASIDE option t
14060 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
14070 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
14080 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  e.** the default
14090 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69   size of lookasi
140a0 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63  de memory on eac
140b0 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
140c0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20  ection]..** The 
140d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
140e0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
140f0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
14100 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
14110 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
14120 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
14130 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
14140 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
14150 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
14160 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  (SQLITE_CONFIG_L
14170 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73  OOKASIDE.** sets
14180 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c   the <i>default<
14190 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
141a0 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
141b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
141c0 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f  DE].** option to
141d0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
141e0 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
141f0 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
14200 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
14210 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
14220 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
14230 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
14240 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14250 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
14260 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14270 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
14280 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14290 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
142a0 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
142b0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
142c0 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
142d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
142e0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
142f0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
14300 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
14310 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e  cifies.** the in
14320 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73  terface to a cus
14330 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
14340 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
14350 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .** ^SQLite make
14360 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
14370 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14380 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14390 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
143a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
143b0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
143c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
143d0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
143e0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
143f0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14400 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
14410 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14420 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
14430 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
14440 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14450 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
14460 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
14470 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74  f.** the current
14480 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
14490 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
144a0 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
144b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
144c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
144d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
144e0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
144f0 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
14500 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
14510 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
14520 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
14530 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
14540 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
14550 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14560 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
14570 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
14580 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
14590 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
145a0 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
145b0 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
145c0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
145d0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
145e0 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
145f0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
14600 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
14610 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
14620 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
14630 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
14640 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
14650 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
14660 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
14670 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
14680 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
14690 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
146a0 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
146b0 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
146c0 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
146d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
146e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
146f0 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
14700 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
14710 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14720 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14730 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
14740 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
14750 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
14760 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
14770 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
14780 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
14790 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
147a0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
147b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
147c0 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
147d0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
147e0 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
147f0 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
14800 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
14810 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
14820 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
14830 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
14840 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
14850 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
14860 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
14870 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
14880 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
14890 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
148a0 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
148b0 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
148c0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
148d0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
148e0 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
148f0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
14900 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
14910 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
14920 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
14930 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
14940 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
14950 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
14960 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
14970 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
14980 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
14990 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
149a0 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
149b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
149c0 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  RI.** <dd>^(The 
149d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
149e0 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  I option takes a
149f0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14a00 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a   of type int..**
14a10 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
14a20 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  en URI handling 
14a30 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
14a40 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
14a50 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a  meter is zero,.*
14a60 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  * then URI handl
14a70 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
14a80 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20  disabled.)^ ^If 
14a90 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14aa0 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62  globally.** enab
14ab0 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
14ac0 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  es passed to [sq
14ad0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
14ae0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
14af0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
14b00 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
14b10 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
14b20 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
14b30 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
14b40 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
14b50 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
14b60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
14b70 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
14b80 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
14b90 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
14ba0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
14bb0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66  n is opened. ^If
14bc0 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
14bd0 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
14be0 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
14bf0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
14c00 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
14c10 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
14c20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
14c30 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
14c40 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
14c50 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20  . ^(By default, 
14c60 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14c70 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
14c80 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
14c90 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
14ca0 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
14cb0 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
14cc0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
14cd0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
14ce0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
14cf0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
14d00 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c  G_INDEX_SCAN]] <
14d10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14d20 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14d30 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SCAN.** <dd>^The
14d40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
14d50 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14d60 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  AN option takes 
14d70 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72  a single integer
14d80 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69  .** argument whi
14d90 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  ch is interprete
14da0 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  d as a boolean i
14db0 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c  n order to enabl
14dc0 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20  e or disable.** 
14dd0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
14de0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
14df0 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
14e00 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70   in the query op
14e10 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65  timizer..** ^The
14e20 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
14e30 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a   is determined.*
14e40 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  * by the [SQLITE
14e50 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f  _ALLOW_COVERING_
14e60 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70  INDEX_SCAN] comp
14e70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
14e80 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69   or is "on".** i
14e90 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74  f that compile-t
14ea0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d  ime option is om
14eb0 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62  itted..** The ab
14ec0 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65  ility to disable
14ed0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
14ee0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
14ef0 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14f00 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20  s.** is because 
14f10 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79  some incorrectly
14f20 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70   coded legacy ap
14f30 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74  plications might
14f40 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20   malfunction.** 
14f50 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a  when the optimiz
14f60 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
14f70 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65  .  Providing the
14f80 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64   ability to.** d
14f90 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d  isable the optim
14fa0 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74  ization allows t
14fb0 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20  he older, buggy 
14fc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
14fd0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
14fe0 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20  out change even 
14ff0 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69  with newer versi
15000 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
15010 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15020 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b  NFIG_PCACHE]] [[
15030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15040 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74  TPCACHE]].** <dt
15050 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
15060 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45  CACHE and SQLITE
15070 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15080 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20  E.** <dd> These 
15090 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f  options are obso
150a0 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20  lete and should 
150b0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e  not be used by n
150c0 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79  ew code..** They
150d0 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f   are retained fo
150e0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
150f0 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72  atibility but ar
15100 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  e now no-ops..**
15110 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
15120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
15130 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  LOG]].** <dt>SQL
15140 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
15150 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  G.** <dd>This op
15160 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
15170 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65  ilable if sqlite
15180 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15190 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
151a0 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20  _ENABLE_SQLLOG] 
151b0 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
151c0 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65  cro defined. The
151d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
151e0 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70  should.** be a p
151f0 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63  ointer to a func
15200 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69  tion of type voi
15210 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
15220 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  e3*,const char*,
15230 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65   int)..** The se
15240 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f  cond should be o
15250 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20  f type (void*). 
15260 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  The callback is 
15270 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c  invoked by the l
15280 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72  ibrary.** in thr
15290 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63  ee separate circ
152a0 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74  umstances, ident
152b0 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c  ified by the val
152c0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
152d0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
152e0 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75  eter. If the fou
152f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15300 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74   0, then the dat
15310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15320 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
15330 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15340 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  t has just been 
15350 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72  opened. The thir
15360 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f  d argument.** po
15370 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72  ints to a buffer
15380 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
15390 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e  name of the main
153a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
153b0 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  If the.** fourth
153c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c   parameter is 1,
153d0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   then the SQL st
153e0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65  atement that the
153f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15400 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61  .** points to ha
15410 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63  s just been exec
15420 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65  uted. Or, if the
15430 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15440 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20  r is 2, then.** 
15450 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  the connection b
15460 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74  eing passed as t
15470 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
15480 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f  ter is being clo
15490 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  sed. The.** thir
154a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  d parameter is p
154b0 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68  assed NULL In th
154c0 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61  is case.  An exa
154d0 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68  mple of using th
154e0 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  is.** configurat
154f0 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ion option can b
15500 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74  e seen in the "t
15510 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f  est_sqllog.c" so
15520 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20  urce file in.** 
15530 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51  the canonical SQ
15540 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65  Lite source tree
15550 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15560 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
15570 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  P_SIZE]].** <dt>
15580 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
15590 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  AP_SIZE.** <dd>^
155a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
155b0 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77  AP_SIZE takes tw
155c0 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  o 64-bit integer
155d0 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29   (sqlite3_int64)
155e0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
155f0 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  are the default 
15600 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20  mmap size limit 
15610 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  (the default set
15620 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41  ting for.** [PRA
15630 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20  GMA mmap_size]) 
15640 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
15650 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
15660 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65  e limit..** ^The
15670 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
15680 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
15690 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62  en by each datab
156a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75  ase connection u
156b0 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74  sing.** either t
156c0 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  he [PRAGMA mmap_
156d0 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f  size] command, o
156e0 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a  r by using the.*
156f0 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
15700 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
15710 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20  control.  ^(The 
15720 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
15730 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c  mmap size.** wil
15740 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72  l be silently tr
15750 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73  uncated if neces
15760 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20  sary so that it 
15770 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20  does not exceed 
15780 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  the.** compile-t
15790 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70  ime maximum mmap
157a0 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65   size set by the
157b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
157c0 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69  MMAP_SIZE] compi
157d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29  le-time option.)
157e0 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20  ^.** ^If either 
157f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
15800 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74   option is negat
15810 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61  ive, then that a
15820 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68  rgument is.** ch
15830 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d  anged to its com
15840 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c  pile-time defaul
15850 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  t..**.** [[SQLIT
15860 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
15870 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  EAPSIZE]].** <dt
15880 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  >SQLITE_CONFIG_W
15890 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a  IN32_HEAPSIZE.**
158a0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
158b0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
158c0 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73  APSIZE option is
158d0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
158e0 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  if SQLite is.** 
158f0 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e  compiled for Win
15900 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53  dows with the [S
15910 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c  QLITE_WIN32_MALL
15920 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OC] pre-processo
15930 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e  r macro.** defin
15940 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  ed. ^SQLITE_CONF
15950 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15960 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74  E takes a 32-bit
15970 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
15980 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20  r value.** that 
15990 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61  specifies the ma
159a0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68  ximum size of th
159b0 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a  e created heap..
159c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
159d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
159e0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
159f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15a00 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _HDRSZ.** <dd>^T
15a10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15a20 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70  _PCACHE_HDRSZ op
15a30 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
15a40 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
15a50 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
15a60 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
15a70 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74  r and writes int
15a80 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74  o that integer t
15a90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
15aa0 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20  ra.** bytes per 
15ab0 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f  page required fo
15ac0 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b  r each page in [
15ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
15ae0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
15af0 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61   amount of extra
15b00 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
15b10 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e  can change depen
15b20 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70  ding on the comp
15b30 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20  iler,.** target 
15b40 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51  platform, and SQ
15b50 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a  Lite version..**
15b60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15b70 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c  FIG_PMASZ]].** <
15b80 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15b90 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54  _PMASZ.** <dd>^T
15ba0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15bb0 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _PMASZ option ta
15bc0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
15bd0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
15be0 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69  is an unsigned i
15bf0 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20  nteger and sets 
15c00 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41  the "Minimum PMA
15c10 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d   Size" for the m
15c20 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20  ultithreaded.** 
15c30 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69  sorter to that i
15c40 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66  nteger.  The def
15c50 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41  ault minimum PMA
15c60 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20   Size is set by 
15c70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  the.** [SQLITE_S
15c80 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d  ORTER_PMASZ] com
15c90 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15ca0 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61  .  New threads a
15cb0 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74  re launched.** t
15cc0 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74  o help with sort
15cd0 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e   operations when
15ce0 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73   multithreaded s
15cf0 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61  orting.** is ena
15d00 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20  bled (using the 
15d10 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d  [PRAGMA threads]
15d20 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68   command) and th
15d30 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74  e amount of cont
15d40 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72  ent.** to be sor
15d50 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20  ted exceeds the 
15d60 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20  page size times 
15d70 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74  the minimum of t
15d80 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61  he.** [PRAGMA ca
15d90 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e  che_size] settin
15da0 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65  g and this value
15db0 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
15dc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15dd0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
15de0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
15df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15e00 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
15e10 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
15e20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15e30 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
15e40 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
15e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15e60 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
15e70 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
15e80 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
15e90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15ea0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
15eb0 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
15ec0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
15ed0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15ee0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
15ef0 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
15f00 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
15f10 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
15f20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15f30 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
15f40 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
15f50 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
15f60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
15f70 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
15f80 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
15f90 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
15fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15fb0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
15fc0 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
15fd0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
15fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15ff0 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
16000 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16010 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
16020 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16030 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
16040 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
16050 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
16060 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
16070 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
16080 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
16090 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
160a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
160b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
160c0 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
160d0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
160e0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
160f0 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e  E       14  /* n
16100 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
16110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16120 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
16130 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
16140 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16150 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
16160 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
16170 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16180 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20  ITE_CONFIG_URI  
16190 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69          17  /* i
161a0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
161b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
161c0 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20  HE2      18  /* 
161d0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
161e0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
161f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16200 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31  G_GETPCACHE2   1
16210 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  9  /* sqlite3_pc
16220 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
16230 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16240 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
16250 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20  _INDEX_SCAN 20  
16260 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
16270 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16280 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20  SQLLOG       21 
16290 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69   /* xSqllog, voi
162a0 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
162b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
162c0 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20  _SIZE    22  /* 
162d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73  sqlite3_int64, s
162e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a  qlite3_int64 */.
162f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16300 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16310 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a  SIZE      23  /*
16320 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64   int nByte */.#d
16330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16340 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
16350 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69          24  /* i
16360 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69  nt *psz */.#defi
16370 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16380 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20  _PMASZ          
16390 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69       25  /* unsi
163a0 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a  gned int szPma *
163b0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
163c0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
163d0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
163e0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
163f0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
16400 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
16410 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
16420 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16430 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
16440 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
16450 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
16460 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
16470 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
16480 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
16490 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
164a0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
164b0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
164c0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
164d0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
164e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
164f0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
16500 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
16510 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
16520 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
16530 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
16540 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
16550 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
16560 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
16570 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
16580 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
16590 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
165a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
165b0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
165c0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
165d0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
165e0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
165f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
16600 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
16610 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
16620 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16630 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
16640 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
16650 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
16660 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
16670 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
16680 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
16690 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
166a0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
166b0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
166c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
166d0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
166e0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
166f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16700 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
16710 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
16720 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
16730 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
16740 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
16750 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
16760 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16770 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
16780 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16790 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
167a0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
167b0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
167c0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
167d0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
167e0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
167f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16800 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
16810 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
16820 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
16830 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
16840 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
16850 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
16860 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
16870 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
16880 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
16890 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
168a0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
168b0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
168c0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
168d0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
168e0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
168f0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
16900 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
16910 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
16920 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
16930 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
16940 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
16950 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16960 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
16970 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
16980 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
16990 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
169a0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
169b0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
169c0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
169d0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
169e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
169f0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
16a00 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
16a10 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
16a20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
16a30 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
16a40 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
16a50 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
16a60 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
16a70 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
16a80 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
16a90 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
16aa0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
16ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16ac0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
16ad0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
16ae0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
16af0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
16b00 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
16b10 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
16b20 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
16b30 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
16b40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
16b50 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
16b60 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
16b70 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
16b80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
16b90 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
16ba0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
16bb0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
16bc0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
16bd0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
16be0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
16bf0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
16c00 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
16c10 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
16c20 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
16c30 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
16c40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
16c50 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
16c60 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
16c70 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16c80 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
16c90 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
16ca0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
16cb0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
16cc0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
16cd0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
16ce0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
16cf0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16d00 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
16d10 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
16d20 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
16d30 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
16d40 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
16d50 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
16d60 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
16d70 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16d80 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
16d90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
16da0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
16db0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
16dc0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
16dd0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
16de0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
16df0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
16e00 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
16e10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16e20 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
16e30 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
16e40 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
16e50 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
16e60 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
16e70 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
16e80 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
16e90 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16ea0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
16eb0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16ec0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
16ed0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
16ee0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
16ef0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
16f00 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
16f10 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
16f20 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
16f30 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16f40 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16f50 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
16f60 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
16f70 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
16f80 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
16f90 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
16fa0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
16fb0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
16fc0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16fd0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
16fe0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
16ff0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
17000 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
17010 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
17020 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
17030 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
17040 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
17050 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
17060 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
17070 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
17080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
17090 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
170a0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
170b0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
170c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
170d0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
170e0 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
170f0 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
17100 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
17110 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
17120 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
17130 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
17140 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
17150 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
17160 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
17170 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
17180 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
17190 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
171a0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
171b0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
171c0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
171d0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
171e0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
171f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
17200 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
17210 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
17220 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
17230 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
17240 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
17250 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
17260 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
17270 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
17280 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
17290 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
172a0 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
172b0 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
172c0 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
172d0 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
172e0 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
172f0 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
17300 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
17310 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
17320 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
17330 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
17340 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
17350 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
17360 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
17370 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
17380 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
17390 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
173a0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
173b0 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
173c0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
173d0 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
173e0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
173f0 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
17400 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
17410 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
17420 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
17430 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
17440 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
17450 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
17460 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
17470 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
17480 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
17490 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
174a0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
174b0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
174c0 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
174d0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
174e0 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
174f0 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
17500 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17510 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
17520 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
17530 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
17540 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17550 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
17560 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
17570 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
17580 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
17590 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
175a0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
175b0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
175c0 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
175d0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
175e0 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
175f0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
17600 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
17610 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
17620 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
17630 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
17640 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
17650 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
17660 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
17670 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
17680 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
17690 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
176a0 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
176b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
176c0 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
176d0 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
176e0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
176f0 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
17700 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
17710 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
17720 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
17730 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
17740 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
17750 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
17760 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
17770 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
17780 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
17790 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
177a0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
177b0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
177c0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
177d0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
177e0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
177f0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
17800 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
17810 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
17820 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
17830 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
17840 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
17850 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
17860 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
17870 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
17880 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
17890 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
178a0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
178b0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
178c0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
178d0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
178e0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
178f0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
17900 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
17910 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
17920 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
17930 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
17940 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
17950 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
17960 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
17970 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
17980 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
17990 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
179a0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
179b0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
179c0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
179d0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
179e0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
179f0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
17a00 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
17a10 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
17a20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
17a30 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
17a40 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
17a50 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
17a60 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
17a70 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
17a80 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
17a90 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
17aa0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
17ab0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
17ac0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
17ad0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
17ae0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
17af0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
17b00 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
17b10 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17b20 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
17b30 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
17b40 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
17b50 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
17b60 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
17b70 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
17b80 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
17b90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
17ba0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17bb0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17bc0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
17bd0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
17be0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17bf0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17c00 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17c10 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
17c20 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
17c30 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
17c40 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
17c50 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
17c60 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
17c70 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
17c80 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ent on the datab
17c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
17ca0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
17cb0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  only parameter..
17cc0 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  ** ^Executing an
17cd0 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
17ce0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
17cf0 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  es not modify th
17d00 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
17d10 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
17d20 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  tion..**.** ^Onl
17d30 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64  y changes made d
17d40 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49  irectly by the I
17d50 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
17d60 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
17d70 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  t are.** conside
17d80 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20  red - auxiliary 
17d90 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
17da0 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  y [CREATE TRIGGE
17db0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a  R | triggers], .
17dc0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
17dd0 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50  actions] or [REP
17de0 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
17df0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20   resolution are 
17e00 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
17e10 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61  .** Changes to a
17e20 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
17e30 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a  ntercepted by .*
17e40 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  * [INSTEAD OF tr
17e50 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20  igger | INSTEAD 
17e60 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65  OF triggers] are
17e70 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54   not counted. ^T
17e80 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74  he value .** ret
17e90 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
17ea0 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64  _changes() immed
17eb0 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20  iately after an 
17ec0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
17ed0 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  r .** DELETE sta
17ee0 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20  tement run on a 
17ef0 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a  view is always z
17f00 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ero. Only change
17f10 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a  s made to real .
17f20 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  ** tables are co
17f30 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
17f40 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d  ngs are more com
17f50 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20  plicated if the 
17f60 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17f70 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  ) function is.**
17f80 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20   executed while 
17f90 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
17fa0 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68  m is running. Th
17fb0 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66  is may happen if
17fc0 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20   the.** program 
17fd0 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65  uses the [change
17fe0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17ff0 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74  ], or if some ot
18000 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  her callback.** 
18010 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  function invokes
18020 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18030 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73  () directly. Ess
18040 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a  entially:.** .**
18050 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
18060 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e  ^(Before enterin
18070 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  g a trigger prog
18080 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65  ram the value re
18090 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
180a0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e      sqlite3_chan
180b0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
180c0 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74  s saved. After t
180d0 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
180e0 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  am .**        ha
180f0 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20  s finished, the 
18100 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69  original value i
18110 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a  s restored.)^.**
18120 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69   .**   <li> ^(Wi
18130 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70  thin a trigger p
18140 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45  rogram each INSE
18150 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
18160 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20  ELETE .**       
18170 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20   statement sets 
18180 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18190 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
181a0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
181b0 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69     upon completi
181c0 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66  on as normal. Of
181d0 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61   course, this va
181e0 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63  lue will not inc
181f0 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  lude .**        
18200 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66  any changes perf
18210 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69  ormed by sub-tri
18220 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71  ggers, as the sq
18230 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
18240 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65  .**        value
18250 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61   will be saved a
18260 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65  nd restored afte
18270 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67  r each sub-trigg
18280 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a  er has run.)^.**
18290 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54   </ul>.** .** ^T
182a0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
182b0 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20  f the changes() 
182c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72  SQL function (or
182d0 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65   similar) is use
182e0 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
182f0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
18300 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
18310 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
18320 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65  igger, it .** re
18330 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
18340 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  as set when the 
18350 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e  calling statemen
18360 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e  t began executin
18370 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  g..** ^If it is 
18380 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  used by the seco
18390 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  nd or subsequent
183a0 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20   such statement 
183b0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
183c0 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68   .** program, th
183d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
183e0 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75   reflects the nu
183f0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
18400 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
18410 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54   previous INSERT
18420 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18430 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
18440 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69  hin the same tri
18450 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gger..**.** See 
18460 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
18470 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18480 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
18490 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
184a0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
184b0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
184c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
184d0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
184e0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
184f0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
18500 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
18510 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
18520 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18530 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
18540 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
18550 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
18560 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
18570 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
18580 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
18590 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
185a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
185b0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
185c0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
185d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
185e0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
185f0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
18600 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
18610 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
18620 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
18630 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
18640 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
18650 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
18660 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
18670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18680 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
18690 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
186a0 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
186b0 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
186c0 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
186d0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
186e0 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
186f0 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
18700 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
18710 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
18720 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
18730 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
18740 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
18750 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
18760 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
18770 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
18780 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
18790 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
187a0 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
187b0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
187c0 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
187d0 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
187e0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
187f0 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
18800 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
18810 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
18820 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
18830 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
18840 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
18850 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
18860 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
18870 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
18880 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
18890 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
188a0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
188b0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
188c0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
188d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
188e0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
188f0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
18900 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
18910 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
18920 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
18930 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
18940 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
18950 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
18960 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18970 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18980 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
18990 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
189a0 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
189b0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
189c0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
189d0 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
189e0 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
189f0 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
18a00 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
18a10 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
18a20 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
18a30 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
18a40 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
18a50 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
18a60 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
18a70 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
18a80 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
18a90 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
18aa0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
18ab0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
18ac0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
18ad0 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
18ae0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
18af0 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
18b00 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
18b10 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
18b20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
18b30 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
18b40 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
18b50 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
18b60 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18b70 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
18b80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18b90 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
18ba0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
18bb0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
18bc0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
18bd0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
18be0 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
18bf0 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
18c00 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
18c10 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
18c20 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18c30 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
18c40 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
18c50 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
18c60 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
18c70 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
18c80 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
18c90 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
18ca0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
18cb0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
18cc0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
18cd0 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
18ce0 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
18cf0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
18d00 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
18d10 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
18d20 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
18d30 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
18d40 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
18d50 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
18d60 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
18d70 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
18d80 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
18d90 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
18da0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
18db0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
18dc0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
18dd0 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
18de0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
18df0 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
18e00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18e10 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
18e20 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
18e30 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
18e40 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
18e50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
18e60 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
18e70 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
18e80 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
18e90 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
18ea0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
18eb0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
18ec0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
18ed0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
18ee0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18ef0 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
18f00 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
18f10 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
18f20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
18f30 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
18f40 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
18f50 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
18f60 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
18f70 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
18f80 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
18f90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
18fa0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
18fb0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
18fc0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
18fd0 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
18fe0 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
18ff0 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
19000 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
19010 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
19020 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
19030 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
19040 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
19050 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
19060 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
19070 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
19080 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
19090 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
190a0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
190b0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
190c0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
190d0 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
190e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
190f0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
19100 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
19110 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
19120 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
19130 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
19140 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
19150 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
19160 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
19170 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
19180 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
19190 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
191a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
191b0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
191c0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
191d0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
191e0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
191f0 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
19200 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
19210 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
19220 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
19230 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
19240 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
19250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
19260 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
19270 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
19280 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
19290 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
192a0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
192b0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
192c0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
192d0 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
192e0 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
192f0 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
19300 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
19310 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
19320 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
19330 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
19340 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
19350 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
19360 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
19370 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
19380 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
19390 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
193a0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
193b0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
193c0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
193d0 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
193e0 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
193f0 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
19400 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
19410 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
19420 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
19430 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
19440 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
19450 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
19460 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
19470 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
19480 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
19490 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
194a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
194b0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
194c0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
194d0 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
194e0 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
194f0 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
19500 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
19510 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
19520 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
19530 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
19540 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
19550 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
19560 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
19570 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
19580 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
19590 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
195a0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
195b0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
195c0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
195d0 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
195e0 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
195f0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
19600 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
19610 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19620 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
19630 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
19640 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
19650 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
19660 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
19670 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
19680 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
19690 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
196a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
196b0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
196c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
196d0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
196e0 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
196f0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
19700 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
19710 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
19720 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
19730 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19740 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
19750 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
19760 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
19770 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
19780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19790 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
197a0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
197b0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
197c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
197d0 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
197e0 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
197f0 64 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dler}.**.** ^The
19800 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19810 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
19820 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
19830 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
19840 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
19850 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
19860 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
19870 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
19880 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
19890 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
198a0 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
198b0 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
198c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
198d0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
198e0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
198f0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
19900 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
19910 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19920 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
19930 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
19940 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
19950 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
19960 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
19970 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
19980 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
19990 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
199a0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
199b0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
199c0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
199d0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
199e0 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
199f0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
19a00 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
19a10 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
19a20 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
19a30 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
19a40 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
19a50 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19a60 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
19a70 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
19a80 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
19a90 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
19aa0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
19ab0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
19ac0 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
19ad0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
19ae0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
19af0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
19b00 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
19b10 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
19b20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19b30 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
19b40 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
19b50 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
19b60 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
19b70 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
19b80 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
19b90 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
19ba0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
19bb0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
19bc0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
19bd0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
19be0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
19bf0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
19c00 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
19c10 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19c20 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
19c30 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
19c40 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
19c50 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
19c60 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
19c70 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
19c80 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
19c90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
19ca0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
19cb0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
19cc0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
19cd0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
19ce0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
19cf0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
19d00 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
19d10 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
19d20 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
19d30 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
19d40 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
19d50 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
19d60 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
19d70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
19d80 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
19d90 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
19da0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
19db0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
19dc0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
19dd0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
19de0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
19df0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
19e00 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
19e10 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
19e20 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
19e30 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
19e40 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
19e50 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
19e60 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
19e70 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
19e80 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
19e90 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
19ea0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
19eb0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
19ec0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
19ed0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
19ee0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
19ef0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
19f00 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
19f10 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
19f20 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
19f30 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
19f40 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
19f50 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
19f60 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
19f70 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
19f80 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
19f90 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
19fa0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
19fb0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
19fc0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
19fd0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
19fe0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
19ff0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1a000 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1a010 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1a020 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1a030 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1a040 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1a050 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1a060 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1a070 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1a080 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1a090 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1a0a0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1a0b0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1a0c0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1a0d0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1a0e0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1a0f0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1a100 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1a110 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1a120 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1a130 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1a140 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1a150 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1a160 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1a170 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1a180 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1a190 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1a1a0 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1a1b0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1a1c0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1a1d0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1a1e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a1f0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1a200 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1a210 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1a220 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1a230 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1a240 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1a250 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1a260 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1a270 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1a280 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1a290 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1a2a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a2b0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1a2c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1a2d0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1a2e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1a2f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1a300 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1a310 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
1a320 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
1a330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a340 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1a350 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
1a360 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1a370 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1a380 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1a390 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1a3a0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1a3b0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1a3c0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1a3d0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1a3e0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1a3f0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1a400 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1a410 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1a420 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1a430 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1a440 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1a450 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1a460 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1a470 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1a480 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1a490 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1a4a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a4b0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1a4c0 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1a4d0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1a4e0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1a4f0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1a500 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1a510 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1a520 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1a530 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1a540 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1a550 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1a560 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1a570 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1a580 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1a590 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1a5a0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1a5b0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1a5c0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1a5d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1a5e0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1a5f0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1a600 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1a610 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1a620 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1a630 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1a640 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1a650 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69  sy_timeout].*/.i
1a660 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1a670 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1a680 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1a690 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1a6a0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1a6b0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1a6c0 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
1a6d0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1a6e0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1a6f0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1a700 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1a710 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1a720 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1a730 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1a740 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1a750 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1a760 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1a770 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1a780 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1a790 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1a7a0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1a7b0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1a7c0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1a7d0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1a7e0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1a7f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1a800 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1a810 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1a820 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1a830 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1a840 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1a850 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1a860 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1a870 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1a880 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1a890 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1a8a0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1a8b0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1a8c0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1a8d0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1a8e0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1a8f0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1a900 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1a910 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1a920 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1a930 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1a940 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1a950 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1a960 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1a970 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1a980 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1a990 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1a9a0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1a9b0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1a9c0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1a9d0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1a9e0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1a9f0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1aa00 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1aa10 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1aa20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1aa30 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1aa40 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1aa50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1aa60 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1aa70 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1aa80 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1aa90 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1aaa0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1aab0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1aac0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1aad0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1aae0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1aaf0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1ab00 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1ab10 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1ab20 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1ab30 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1ab40 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1ab50 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1ab60 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1ab70 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1ab80 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1ab90 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1aba0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1abb0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1abc0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1abd0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1abe0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1abf0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1ac00 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1ac10 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ac20 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1ac30 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1ac40 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1ac50 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1ac60 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1ac70 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1ac80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1ac90 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1aca0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1acb0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1acc0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1acd0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1ace0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1acf0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1ad00 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1ad10 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1ad20 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1ad30 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1ad40 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1ad50 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1ad60 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ad70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ad80 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1ad90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ada0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1adb0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1adc0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1add0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1ade0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1adf0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1ae00 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1ae10 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1ae20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ae30 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1ae40 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1ae50 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1ae60 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1ae70 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1ae80 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1ae90 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1aea0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1aeb0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1aec0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1aed0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1aee0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1aef0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1af00 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1af10 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1af20 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1af30 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1af40 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1af50 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1af60 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1af70 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1af80 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1af90 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1afa0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1afb0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1afc0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1afd0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1afe0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1aff0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1b000 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1b010 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1b020 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1b030 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1b040 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1b050 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1b060 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1b070 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1b080 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1b090 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b0a0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1b0b0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1b0c0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1b0d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b0e0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1b0f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1b100 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1b110 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1b120 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1b130 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1b140 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1b150 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1b160 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1b170 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1b180 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1b190 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1b1a0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1b1b0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1b1c0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1b1d0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1b1e0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1b1f0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1b200 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1b210 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1b220 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1b230 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1b240 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1b250 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1b260 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1b270 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1b280 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1b290 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1b2a0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1b2b0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1b2c0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1b2d0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1b2e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1b2f0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
1b300 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1b310 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1b320 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1b330 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1b340 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1b350 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1b360 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1b370 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1b380 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1b390 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1b3a0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1b3b0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1b3c0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1b3d0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1b3e0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1b3f0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1b400 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1b410 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1b420 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1b430 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1b440 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1b450 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1b460 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
1b470 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1b480 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1b490 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1b4a0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1b4b0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1b4c0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1b4d0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1b4e0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1b4f0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1b500 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1b510 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1b520 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1b530 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1b540 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20  understand most 
1b550 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26  of the common K&
1b560 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  R formatting opt
1b570 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f  ions,.** plus so
1b580 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f  me additional no
1b590 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61  n-standard forma
1b5a0 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c  ts, detailed bel
1b5b0 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ow..** Note that
1b5c0 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72   some of the mor
1b5d0 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74  e obscure format
1b5e0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f  ting options fro
1b5f0 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69  m recent.** C-li
1b600 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20  brary standards 
1b610 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d  are omitted from
1b620 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61   this implementa
1b630 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
1b640 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1b650 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1b660 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1b670 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1b680 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1b690 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1b6a0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1b6b0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1b6c0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1b6d0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1b6e0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1b6f0 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1b700 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1b710 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1b720 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1b730 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1b740 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1b750 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1b760 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1b770 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1b780 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1b790 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1b7a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b7b0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1b7c0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1b7d0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1b7e0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1b7f0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1b800 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1b810 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1b820 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1b830 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b840 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1b850 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1b860 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1b870 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1b880 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1b890 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1b8a0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1b8b0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1b8c0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1b8d0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1b8e0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1b8f0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1b900 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1b910 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1b920 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1b930 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1b940 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1b950 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1b960 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1b970 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1b980 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1b990 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1b9a0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1b9b0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1b9c0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1b9d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1b9e0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1b9f0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1ba00 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1ba10 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1ba20 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1ba30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1ba40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1ba50 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1ba60 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1ba70 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1ba80 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1ba90 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1baa0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1bab0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1bac0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1bad0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1bae0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1baf0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1bb00 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1bb10 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1bb20 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1bb30 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1bb40 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1bb50 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1bb60 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1bb70 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1bb80 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1bb90 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1bba0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1bbb0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1bbc0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1bbd0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1bbe0 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1bbf0 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1bc00 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1bc10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1bc20 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1bc30 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1bc40 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1bc50 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1bc60 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1bc70 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1bc80 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1bc90 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1bca0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1bcb0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1bcc0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1bcd0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1bce0 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20   "%Q", "%w" and 
1bcf0 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
1bd00 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74  .** ^(The %q opt
1bd10 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1bd20 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
1bd30 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74  stitutes a nul-t
1bd40 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1bd50 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
1bd60 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
1bd70 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
1bd80 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
1bd90 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
1bda0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
1bdb0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
1bdc0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
1bdd0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
1bde0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
1bdf0 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
1be00 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
1be10 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
1be20 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
1be30 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
1be40 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
1be50 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
1be60 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
1be70 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
1be80 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1be90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1bea0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
1beb0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
1bec0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
1bed0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1bee0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
1bef0 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
1bf00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1bf10 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1bf20 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1bf30 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1bf40 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1bf50 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1bf60 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
1bf70 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
1bf80 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1bf90 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1bfa0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1bfb0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1bfc0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1bfd0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
1bfe0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
1bff0 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
1c000 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
1c010 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
1c020 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
1c030 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
1c040 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1c050 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c060 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1c070 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1c080 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
1c090 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
1c0a0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c0b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
1c0c0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
1c0d0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
1c0e0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
1c0f0 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
1c100 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
1c110 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
1c120 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c130 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1c140 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1c150 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1c160 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
1c170 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c180 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
1c190 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
1c1a0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
1c1b0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
1c1c0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
1c1d0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
1c1e0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
1c1f0 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
1c200 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
1c210 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
1c220 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
1c230 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
1c240 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
1c250 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
1c260 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
1c270 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
1c280 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
1c290 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
1c2a0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
1c2b0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
1c2c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
1c2d0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
1c2e0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
1c2f0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
1c300 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
1c310 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
1c320 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
1c330 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c340 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1c350 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1c360 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1c370 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1c380 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
1c390 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1c3a0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1c3b0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1c3c0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1c3d0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c3e0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
1c3f0 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
1c400 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
1c410 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1c420 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
1c430 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
1c440 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
1c450 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1c460 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
1c470 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
1c480 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25  ption is like "%
1c490 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69  q" except that i
1c4a0 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20  t expects to.** 
1c4b0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  be contained wit
1c4c0 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  hin double-quote
1c4d0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e  s instead of sin
1c4e0 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20  gle quotes, and 
1c4f0 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68  it.** escapes th
1c500 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63  e double-quote c
1c510 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64  haracter instead
1c520 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71   of the single-q
1c530 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65  uote.** characte
1c540 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66  r.)^  The "%w" f
1c550 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1c560 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
1c570 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e   safely insertin
1c580 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63  g.** table and c
1c590 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f  olumn names into
1c5a0 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53   a constructed S
1c5b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1c5c0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1c5d0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1c5e0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1c5f0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1c600 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1c610 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1c620 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1c630 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1c640 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1c650 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1c660 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1c670 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1c680 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
1c690 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1c6a0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
1c6b0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1c6c0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1c6d0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
1c6e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
1c6f0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1c700 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72  har*, ...);.char
1c710 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1c720 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1c730 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1c740 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1c750 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1c760 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1c770 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1c780 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1c790 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1c7a0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1c7b0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1c7c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c7d0 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1c7e0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1c7f0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1c800 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1c810 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1c820 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1c830 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1c840 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1c850 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1c860 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1c870 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1c880 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1c890 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c8a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1c8b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1c8c0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1c8d0 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1c8e0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1c8f0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1c900 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1c910 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c920 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1c930 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1c940 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1c950 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1c960 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1c970 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1c980 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1c990 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1c9a0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1c9b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c9c0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1c9d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1c9e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1c9f0 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69  alloc64(N) routi
1ca00 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69  ne works just li
1ca10 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ke.** sqlite3_ma
1ca20 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74  lloc(N) except t
1ca30 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69  hat N is an unsi
1ca40 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65  gned 64-bit inte
1ca50 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1ca60 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69  f a signed 32-bi
1ca70 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
1ca80 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1ca90 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1caa0 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1cab0 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1cac0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1cad0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1cae0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1caf0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1cb00 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1cb10 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1cb20 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1cb30 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1cb40 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1cb50 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1cb60 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1cb70 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1cb80 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1cb90 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1cba0 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1cbb0 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1cbc0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1cbd0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1cbe0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1cbf0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1cc00 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1cc10 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1cc20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1cc30 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1cc40 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1cc50 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1cc60 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1cc70 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1cc80 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1cc90 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1cca0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1ccb0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1ccc0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1ccd0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1cce0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1ccf0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1cd00 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1cd10 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  c()..**.** ^The 
1cd20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cd30 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61  X,N) interface a
1cd40 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1cd50 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1cd60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58  ory allocation X
1cd70 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1cd80 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  N bytes..** ^If 
1cd90 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
1cda0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1cdb0 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20  oc(X,N).** is a 
1cdc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1cdd0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1cde0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1cdf0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1ce00 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20  3_malloc(N)..** 
1ce10 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ^If the N parame
1ce20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1ce30 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a  ealloc(X,N) is z
1ce40 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1ce50 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1ce60 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1ce70 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1ce80 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1ce90 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69  ree(X)..** ^sqli
1cea0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1ceb0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1cec0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1ced0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1cee0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1cef0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1cf00 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
1cf10 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c   memory is avail
1cf20 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1cf30 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1cf40 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1cf50 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1cf60 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1cf70 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1cf80 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1cf90 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1cfa0 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1cfb0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1cfc0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61  3_realloc(X,N) a
1cfd0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1cfe0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1cff0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1d000 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1d010 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  turns NULL and N
1d020 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
1d030 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20  en the.** prior 
1d040 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f  allocation is no
1d050 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1d060 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1d070 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72  loc64(X,N) inter
1d080 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20  faces works the 
1d090 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
1d0a0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1d0b0 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1d0c0 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e   a 64-bit unsign
1d0d0 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  ed integer inste
1d0e0 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69  ad.** of a 32-bi
1d0f0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1d100 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73  ..**.** ^If X is
1d110 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1d120 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  tion previously 
1d130 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1d140 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a  lite3_malloc(),.
1d150 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1d160 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  c64(), sqlite3_r
1d170 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c  ealloc(), or sql
1d180 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1d190 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
1d1a0 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1d1b0 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
1d1c0 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hat memory alloc
1d1d0 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a  ation in bytes..
1d1e0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  ** ^The value re
1d1f0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1d200 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74  3_msize(X) might
1d210 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
1d220 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
1d230 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64   bytes requested
1d240 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f   when X was allo
1d250 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73  cated.  ^If X is
1d260 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1d270 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
1d280 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73  msize(X) returns
1d290 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69   zero.  If X poi
1d2a0 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67  nts to something
1d2b0 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20   that is not.** 
1d2c0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1d2d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1d2e0 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69  on, or if it poi
1d2f0 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c  nts to a formerl
1d300 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72  y.** valid memor
1d310 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61  y allocation tha
1d320 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66  t has now been f
1d330 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  reed, then the b
1d340 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71  ehavior.** of sq
1d350 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69  lite3_msize(X) i
1d360 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
1d370 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c  possibly harmful
1d380 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1d390 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1d3a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d3b0 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1d3c0 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1d3d0 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20  malloc64(), and 
1d3e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1d3f0 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  4().** is always
1d400 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1d410 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1d420 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1d430 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1d440 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1d450 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1d460 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1d470 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1d480 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1d490 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1d4a0 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1d4b0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1d4c0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1d4d0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1d4e0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1d4f0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1d500 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1d510 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1d520 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1d530 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1d540 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1d550 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1d560 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1d570 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1d580 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1d590 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1d5a0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1d5b0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1d5c0 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1d5d0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1d5e0 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1d5f0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1d600 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1d610 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1d620 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1d630 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1d640 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1d650 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1d660 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1d670 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1d680 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1d690 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1d6a0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1d6b0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1d6c0 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1d6d0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1d6e0 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1d6f0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1d700 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1d710 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1d720 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1d730 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1d740 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1d750 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1d760 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1d770 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1d780 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1d790 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1d7a0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1d7b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1d7c0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1d7d0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1d7e0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1d7f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1d800 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1d810 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1d820 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1d830 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1d840 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1d850 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1d860 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1d870 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1d880 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1d890 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1d8a0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1d8b0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1d8c0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1d8d0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
1d8e0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1d8f0 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64(sqlite3_uint6
1d900 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  4);.void *sqlite
1d910 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1d920 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c   int);.void *sql
1d930 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76  ite3_realloc64(v
1d940 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
1d950 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
1d960 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
1d970 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20  .sqlite3_uint64 
1d980 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f  sqlite3_msize(vo
1d990 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1d9a0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1d9b0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1d9c0 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1d9d0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1d9e0 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1d9f0 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1da00 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1da10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1da20 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1da30 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1da40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1da50 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1da60 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1da70 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1da80 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1da90 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1daa0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1dab0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1dac0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1dad0 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1dae0 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1daf0 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1db00 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1db10 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1db20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1db30 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1db40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1db50 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1db60 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1db70 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1db80 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1db90 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1dba0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1dbb0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1dbc0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1dbd0 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1dbe0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1dbf0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1dc00 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1dc10 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1dc20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1dc30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1dc40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1dc50 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1dc60 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1dc70 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1dc80 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1dc90 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1dca0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1dcb0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1dcc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1dcd0 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1dce0 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1dcf0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1dd00 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1dd10 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1dd20 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1dd30 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1dd40 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1dd50 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1dd60 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1dd70 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1dd80 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1dd90 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1dda0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1ddb0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1ddc0 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1ddd0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
1dde0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1ddf0 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
1de00 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1de10 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1de20 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
1de30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1de40 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
1de50 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
1de60 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
1de70 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
1de80 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
1de90 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
1dea0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
1deb0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
1dec0 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
1ded0 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
1dee0 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
1def0 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
1df00 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
1df10 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
1df20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
1df30 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
1df40 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
1df50 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
1df60 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
1df70 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
1df80 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
1df90 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
1dfa0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
1dfb0 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
1dfc0 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
1dfd0 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
1dfe0 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
1dff0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
1e000 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
1e010 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
1e020 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72  P..** ^The P par
1e030 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20  ameter can be a 
1e040 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e050 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75  .** ^If this rou
1e060 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65  tine has not bee
1e070 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c  n previously cal
1e080 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72  led or if the pr
1e090 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68  evious.** call h
1e0a0 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f  ad N less than o
1e0b0 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ne or a NULL poi
1e0c0 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e  nter for P, then
1e0d0 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20   the PRNG is.** 
1e0e0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1e0f0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
1e100 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1e110 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a  mness method of.
1e120 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  ** the default [
1e130 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1e140 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
1e150 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
1e160 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1e170 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
1e180 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e  ore and a.** non
1e190 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65  -NULL P then the
1e1a0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
1e1b0 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
1e1c0 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
1e1d0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
1e1e0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
1e1f0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
1e200 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
1e210 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
1e220 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
1e230 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
1e240 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1e250 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
1e260 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
1e270 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1e280 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1e290 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1e2a0 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1e2b0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1e2c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1e2d0 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1e2e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1e2f0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1e300 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e310 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1e320 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1e330 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
1e340 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
1e350 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1e360 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
1e370 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
1e380 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e390 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
1e3a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e3b0 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
1e3c0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
1e3d0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
1e3e0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
1e3f0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
1e400 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
1e410 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
1e420 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
1e430 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1e440 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
1e450 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
1e460 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
1e470 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
1e480 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
1e490 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
1e4a0 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
1e4b0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
1e4c0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
1e4d0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
1e4e0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
1e4f0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
1e500 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1e510 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
1e520 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
1e530 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
1e540 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
1e550 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1e560 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
1e570 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
1e580 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1e590 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
1e5a0 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
1e5b0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1e5c0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
1e5d0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
1e5e0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
1e5f0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1e600 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1e610 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1e620 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1e630 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1e640 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1e650 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1e660 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
1e670 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1e680 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
1e690 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1e6a0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
1e6b0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
1e6c0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1e6d0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1e6e0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
1e6f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e700 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1e710 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1e720 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
1e730 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1e740 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1e750 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
1e760 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
1e770 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
1e780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1e790 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
1e7a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e7b0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1e7c0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
1e7d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1e7e0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1e7f0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
1e800 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
1e810 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
1e820 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1e830 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
1e840 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
1e850 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
1e860 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
1e870 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1e880 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1e890 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
1e8a0 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
1e8b0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
1e8c0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
1e8d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1e8e0 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
1e8f0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
1e900 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1e910 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1e920 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1e930 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1e940 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1e950 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
1e960 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1e970 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
1e980 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
1e990 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e9a0 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
1e9b0 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
1e9c0 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
1e9d0 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
1e9e0 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1e9f0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1ea00 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
1ea10 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
1ea20 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
1ea30 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
1ea40 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
1ea50 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
1ea60 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
1ea70 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
1ea80 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
1ea90 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
1eaa0 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
1eab0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1eac0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
1ead0 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
1eae0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
1eaf0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1eb00 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
1eb10 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1eb20 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
1eb30 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
1eb40 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
1eb50 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
1eb60 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
1eb70 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
1eb80 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
1eb90 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
1eba0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1ebb0 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
1ebc0 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
1ebd0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
1ebe0 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
1ebf0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
1ec00 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
1ec10 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
1ec20 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
1ec30 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
1ec40 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
1ec50 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
1ec60 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
1ec70 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
1ec80 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
1ec90 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
1eca0 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
1ecb0 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
1ecc0 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
1ecd0 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
1ece0 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
1ecf0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
1ed00 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
1ed10 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
1ed20 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
1ed30 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
1ed40 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
1ed50 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
1ed60 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
1ed70 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
1ed80 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
1ed90 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
1eda0 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
1edb0 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
1edc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1edd0 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
1ede0 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
1edf0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
1ee00 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1ee10 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
1ee20 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
1ee30 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
1ee40 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
1ee50 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
1ee60 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
1ee70 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
1ee80 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
1ee90 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1eea0 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
1eeb0 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
1eec0 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
1eed0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1eee0 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
1eef0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
1ef00 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
1ef10 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
1ef20 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
1ef30 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
1ef40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ef50 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
1ef60 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
1ef70 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1ef80 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
1ef90 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
1efa0 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
1efb0 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
1efc0 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
1efd0 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
1efe0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1eff0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
1f000 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
1f010 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1f020 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1f030 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1f040 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1f050 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1f060 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1f070 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
1f080 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
1f090 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1f0a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f0b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1f0c0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1f0d0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1f0e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f0f0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1f100 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1f110 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1f120 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
1f130 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f140 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
1f150 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1f160 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
1f170 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
1f180 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
1f190 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f1a0 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
1f1b0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
1f1c0 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
1f1d0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
1f1e0 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1f1f0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
1f200 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
1f210 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
1f220 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1f230 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1f240 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
1f250 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f260 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1f270 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
1f280 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1f290 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1f2a0 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
1f2b0 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
1f2c0 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
1f2d0 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
1f2e0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
1f2f0 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
1f300 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
1f310 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
1f320 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
1f330 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
1f340 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f350 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
1f360 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
1f370 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
1f380 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
1f390 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1f3a0 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
1f3b0 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
1f3c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
1f3d0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1f3e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1f3f0 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
1f400 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
1f410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f420 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
1f430 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1f440 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1f450 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1f460 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f470 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
1f480 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
1f490 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
1f4a0 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
1f4b0 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
1f4c0 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
1f4d0 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
1f4e0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
1f4f0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
1f500 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
1f510 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f520 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1f530 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
1f540 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1f550 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1f560 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
1f570 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
1f580 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63  lso used as a [c
1f590 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69  onflict resoluti
1f5a0 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75  on mode].** retu
1f5b0 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73  rned from the [s
1f5c0 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
1f5d0 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
1f5e0 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
1f5f0 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
1f600 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
1f610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
1f620 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
1f630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
1f640 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
1f650 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
1f660 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
1f670 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
1f680 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f690 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
1f6a0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1f6b0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1f6c0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
1f6d0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
1f6e0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1f6f0 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
1f700 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
1f710 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
1f720 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
1f730 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
1f740 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1f750 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1f760 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
1f770 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1f780 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
1f790 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
1f7a0 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
1f7b0 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
1f7c0 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
1f7d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f7e0 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
1f7f0 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
1f800 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
1f810 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
1f820 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
1f830 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
1f840 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1f850 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
1f860 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
1f870 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
1f880 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f890 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
1f8a0 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
1f8b0 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
1f8c0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
1f8d0 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
1f8e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1f8f0 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
1f900 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1f910 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1f920 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1f930 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1f940 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1f950 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1f960 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
1f970 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
1f980 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1f990 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
1f9a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1f9b0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
1f9c0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
1f9d0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
1f9e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
1f9f0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
1fa00 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
1fa10 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
1fa20 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
1fa30 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
1fa40 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
1fa50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fa60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fa70 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
1fa80 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
1fa90 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
1faa0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
1fab0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
1fac0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1fad0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1faf0 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
1fb00 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
1fb10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1fb20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fb30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fb40 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
1fb50 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
1fb60 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1fb70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1fb80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fb90 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
1fba0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
1fbb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1fbc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fbd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1fbe0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
1fbf0 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
1fc00 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1fc10 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fc20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1fc30 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
1fc40 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
1fc50 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1fc60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fc70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fc80 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
1fc90 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
1fca0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1fcb0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fcc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fcd0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
1fce0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
1fcf0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1fd00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fd10 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
1fd20 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1fd30 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
1fd40 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1fd50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fd60 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
1fd70 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
1fd80 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
1fd90 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1fda0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1fdb0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
1fdc0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
1fdd0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fde0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fdf0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fe00 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1fe10 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
1fe20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1fe30 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1fe40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fe50 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1fe60 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
1fe70 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1fe80 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fe90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fea0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1feb0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
1fec0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1fed0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1fee0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fef0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
1ff00 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
1ff10 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1ff20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ff30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ff40 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
1ff50 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
1ff60 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1ff70 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ff80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ff90 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
1ffa0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
1ffb0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1ffc0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ffd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ffe0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
1fff0 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
20000 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20010 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20030 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
20040 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
20050 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
20060 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
20070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20080 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
20090 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
200a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
200b0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
200c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
200d0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
200e0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
200f0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
20100 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
20120 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
20130 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
20140 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
20150 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
20170 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
20180 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
20190 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
201a0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
201b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
201c0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
201d0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
201e0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
201f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20200 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
20210 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
20220 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
20230 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
20240 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20250 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
20260 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
20270 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
20280 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
20290 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
202a0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
202b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
202c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
202d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
202e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
202f0 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
20300 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
20310 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20320 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20330 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20340 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
20350 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
20360 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20370 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
20380 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20390 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
203a0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
203b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
203c0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
203d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
203e0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
203f0 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
20400 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
20410 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
20420 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20430 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
20440 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
20450 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
20460 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
20470 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20480 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
20490 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
204a0 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
204b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
204c0 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
204d0 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55        33   /* NU
204e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
204f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20510 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
20520 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
20530 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
20540 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
20550 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20560 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
20570 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
20580 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
20590 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
205a0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
205b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
205c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
205d0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
205e0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
205f0 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
20600 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
20610 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
20620 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
20630 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
20640 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
20650 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
20660 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
20670 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
20680 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
20690 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
206a0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
206b0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
206c0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
206d0 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
206e0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
206f0 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
20700 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
20710 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
20720 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
20730 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
20740 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
20750 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
20760 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
20770 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
20780 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  igger.)^.**.** T
20790 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
207a0 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
207b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
207c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
207d0 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e  limit.** the len
207e0 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  gth of [bound pa
207f0 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69  rameter] expansi
20800 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74  on in the output
20810 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63   of sqlite3_trac
20820 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e()..**.** ^The 
20830 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
20840 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
20850 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
20860 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
20870 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
20880 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
20890 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
208a0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
208b0 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
208c0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
208d0 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
208e0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
208f0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
20900 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
20910 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
20920 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20930 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
20940 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
20950 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
20960 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
20970 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
20980 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
20990 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
209a0 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
209b0 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
209c0 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
209d0 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
209e0 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
209f0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
20a00 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
20a10 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
20a20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
20a30 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
20a40 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
20a50 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
20a60 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
20a70 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
20a80 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
20a90 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
20aa0 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
20ab0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
20ac0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
20ad0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
20ae0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
20af0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
20b00 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
20b10 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
20b20 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
20b30 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
20b40 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
20b50 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
20b60 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
20b70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
20b80 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
20b90 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
20ba0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
20bb0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
20bc0 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
20bd0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
20be0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
20bf0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
20c00 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
20c10 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
20c20 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
20c30 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
20c40 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
20c50 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
20c60 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
20c70 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
20c80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20c90 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
20ca0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
20cb0 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
20cc0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
20cd0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
20ce0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
20cf0 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
20d00 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
20d10 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
20d20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
20d30 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
20d40 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
20d50 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
20d60 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62  approximate numb
20d70 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75  er of .** [virtu
20d80 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72  al machine instr
20d90 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72  uctions] that ar
20da0 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77  e evaluated betw
20db0 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a  een successive.*
20dc0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
20dd0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e   the callback X.
20de0 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20    ^If N is less 
20df0 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68  than one then th
20e00 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61  e progress.** ha
20e10 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65  ndler is disable
20e20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  d..**.** ^Only a
20e30 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
20e40 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
20e50 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
20e60 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
20e70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
20e80 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
20e90 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
20ea0 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
20eb0 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
20ec0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
20ed0 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
20ee0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
20ef0 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
20f00 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
20f10 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
20f20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
20f30 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
20f40 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
20f50 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
20f60 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20f70 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
20f80 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
20f90 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
20fa0 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
20fb0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
20fc0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
20fd0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
20fe0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
20ff0 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
21000 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
21010 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
21020 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
21030 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
21040 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21050 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
21060 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
21070 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
21080 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
21090 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
210a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
210b0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
210c0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
210d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
210e0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
210f0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
21100 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
21110 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
21120 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
21130 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
21140 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
21150 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
21160 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
21170 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
21180 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
21190 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
211a0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
211b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
211c0 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
211d0 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
211e0 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
211f0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
21200 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
21210 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
21220 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
21230 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
21240 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
21250 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
21260 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
21270 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
21280 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
21290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
212a0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
212b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
212c0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
212d0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
212e0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
212f0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
21300 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
21310 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
21320 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
21330 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
21340 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
21350 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
21360 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
21370 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
21380 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
21390 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
213a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
213b0 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
213c0 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
213d0 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
213e0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
213f0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
21400 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
21410 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
21420 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
21430 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
21440 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
21450 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
21460 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
21470 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
21480 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
21490 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
214a0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
214b0 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
214c0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
214d0 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
214e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
214f0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
21500 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
21510 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
21520 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
21530 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
21540 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
21550 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
21560 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
21570 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
21580 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
21590 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
215a0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
215b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
215c0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
215d0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
215e0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
215f0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
21600 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
21610 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
21620 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
21630 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
21640 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
21650 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
21660 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
21670 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
21680 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
21690 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
216a0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
216b0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
216c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
216d0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
216e0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
216f0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
21700 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
21710 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
21720 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
21730 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
21740 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
21750 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
21760 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
21770 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
21780 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
21790 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
217a0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
217b0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
217c0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
217d0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
217e0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
217f0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
21800 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
21810 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
21820 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
21830 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
21840 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
21850 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
21860 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
21870 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
21880 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
21890 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
218a0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
218b0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
218c0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
218d0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
218e0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
218f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
21900 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21910 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
21920 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
21930 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21940 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
21950 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
21960 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
21970 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
21980 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
21990 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
219a0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
219b0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
219c0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
219d0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
219e0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
219f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
21a00 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
21a10 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
21a20 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
21a30 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
21a40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21a50 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21a60 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
21a70 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
21a80 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
21a90 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
21aa0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
21ab0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
21ac0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
21ad0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
21ae0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
21af0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
21b00 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
21b10 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
21b20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
21b30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21b40 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
21b50 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
21b60 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
21b70 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
21b80 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
21b90 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
21ba0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
21bb0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
21bc0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
21bd0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
21be0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
21bf0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
21c00 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
21c10 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
21c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
21c30 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
21c40 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
21c50 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
21c60 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
21c70 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
21c80 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
21c90 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
21ca0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
21cb0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
21cc0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
21cd0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
21ce0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
21cf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
21d00 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
21d10 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
21d20 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
21d30 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
21d40 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
21d50 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
21d60 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
21d70 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
21d80 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
21d90 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
21da0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
21db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21dc0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
21dd0 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
21de0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
21df0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
21e00 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
21e10 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
21e20 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
21e30 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
21e40 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
21e50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
21e60 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
21e70 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
21e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21e90 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
21ea0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
21eb0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
21ec0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
21ed0 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
21ee0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
21ef0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21f00 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
21f10 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
21f20 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
21f30 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
21f40 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21f50 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
21f60 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
21f70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21f80 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
21f90 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
21fa0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
21fb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
21fc0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
21fd0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
21fe0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
21ff0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
22000 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
22010 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
22020 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
22030 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
22040 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
22050 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
22060 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
22070 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
22080 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
22090 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
220a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
220b0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
220c0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
220d0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
220e0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
220f0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
22100 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
22110 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
22120 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
22130 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
22140 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
22150 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
22160 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
22170 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
22180 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
22190 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
221a0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
221b0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
221c0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
221d0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
221e0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
221f0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
22200 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
22210 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
22220 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
22230 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
22240 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
22250 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
22260 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
22270 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
22280 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
22290 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
222a0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
222b0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
222c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
222d0 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
222e0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
222f0 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
22300 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
22310 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
22320 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
22330 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
22340 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
22350 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
22360 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22370 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
22380 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
22390 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
223a0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
223b0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
223c0 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
223d0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
223e0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
223f0 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
22400 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
22410 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
22420 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
22430 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
22440 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
22450 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
22460 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
22470 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
22480 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
22490 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
224a0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
224b0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
224c0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
224d0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
224e0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
224f0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
22500 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
22510 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
22520 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
22530 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
22540 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
22550 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
22560 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
22570 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
22580 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
22590 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
225a0 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
225b0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
225c0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
225d0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
225e0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
225f0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22600 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
22610 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
22620 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
22630 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
22640 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
22650 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
22660 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
22670 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
22680 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
22690 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
226a0 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
226b0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
226c0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
226d0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
226e0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
226f0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
22700 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
22710 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
22720 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
22730 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
22740 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
22750 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
22760 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
22770 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
22780 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
22790 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
227a0 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
227b0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
227c0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
227d0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
227e0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
227f0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
22800 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22810 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
22820 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
22830 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
22840 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
22850 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
22860 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
22870 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
22880 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
22890 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
228a0 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
228b0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
228c0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
228d0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
228e0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
228f0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
22900 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
22910 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
22920 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
22930 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
22940 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
22950 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
22960 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
22970 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
22980 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
22990 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
229a0 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
229b0 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
229c0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
229d0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
229e0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
229f0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
22a00 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
22a10 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
22a20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
22a30 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
22a40 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
22a50 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22a60 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
22a70 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
22a80 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
22a90 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
22aa0 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
22ab0 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
22ac0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
22ad0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
22ae0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
22af0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
22b00 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
22b10 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
22b20 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
22b30 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
22b40 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
22b50 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
22b60 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
22b70 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
22b80 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
22b90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
22ba0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
22bb0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
22bc0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
22bd0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
22be0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
22bf0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
22c00 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
22c10 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
22c20 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
22c30 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
22c40 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
22c50 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
22c60 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
22c70 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
22c80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22c90 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
22ca0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
22cb0 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
22cc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
22cd0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
22ce0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
22cf0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
22d00 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
22d10 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
22d20 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
22d30 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
22d40 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
22d50 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
22d60 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
22d70 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
22d80 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
22d90 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
22da0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
22db0 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
22dc0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
22dd0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
22de0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
22df0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
22e00 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
22e10 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
22e20 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
22e30 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
22e40 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
22e50 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
22e60 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
22e70 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
22e80 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
22e90 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
22ea0 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
22eb0 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
22ec0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
22ed0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
22ee0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
22ef0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
22f00 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
22f10 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
22f20 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
22f30 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
22f40 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
22f50 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
22f60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
22f70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
22f80 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
22f90 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
22fa0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
22fb0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
22fc0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
22fd0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
22fe0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
22ff0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
23000 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
23010 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
23020 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
23030 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
23040 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
23050 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
23060 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
23070 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
23080 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
23090 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
230a0 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
230b0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
230c0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
230d0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
230e0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
230f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
23100 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
23110 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
23120 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
23130 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
23140 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
23150 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
23160 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
23170 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
23180 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
23190 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
231a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
231b0 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
231c0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
231d0 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
231e0 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
231f0 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
23200 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
23210 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
23220 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
23230 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
23240 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
23250 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
23260 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
23270 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
23280 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
23290 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
232a0 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
232b0 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
232c0 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
232d0 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
232e0 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
232f0 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
23300 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
23310 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
23320 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
23330 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
23340 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
23350 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
23360 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
23370 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
23380 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
23390 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
233a0 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
233b0 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
233c0 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
233d0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
233e0 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
233f0 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
23400 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
23410 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
23420 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
23430 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
23440 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
23450 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
23460 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
23470 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
23480 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
23490 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
234a0 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
234b0 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
234c0 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
234d0 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
234e0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
234f0 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
23500 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
23510 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
23520 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
23530 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
23540 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
23550 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
23560 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
23570 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
23580 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
23590 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
235a0 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
235b0 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
235c0 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
235d0 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
235e0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
235f0 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
23600 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
23610 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
23620 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
23630 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
23640 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
23650 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
23660 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
23670 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
23680 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
23690 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
236a0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
236b0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
236c0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
236d0 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
236e0 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
236f0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
23700 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
23710 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
23720 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
23730 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
23740 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
23750 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
23760 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
23770 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
23780 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
23790 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
237a0 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
237b0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
237c0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
237d0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
237e0 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
237f0 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
23800 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
23810 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
23820 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
23830 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
23840 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
23850 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
23860 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
23870 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
23880 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
23890 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
238a0 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
238b0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
238c0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
238d0 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
238e0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
238f0 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
23900 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
23910 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23920 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
23930 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
23940 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
23950 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
23960 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
23970 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
23980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
23990 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
239a0 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
239b0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
239c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
239d0 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
239e0 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
239f0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
23a00 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
23a10 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
23a20 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
23a30 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
23a40 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
23a50 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
23a60 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
23a70 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
23a80 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
23a90 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
23aa0 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
23ab0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
23ac0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
23ad0 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
23ae0 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
23af0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
23b00 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
23b10 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
23b20 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
23b30 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
23b40 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
23b50 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
23b60 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
23b70 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
23b80 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
23b90 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
23ba0 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
23bb0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
23bc0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
23bd0 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
23be0 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
23bf0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
23c00 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
23c10 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
23c20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
23c30 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23c40 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
23c50 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
23c60 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
23c70 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23c80 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
23c90 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
23ca0 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
23cb0 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
23cc0 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
23cd0 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
23ce0 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
23cf0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
23d00 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
23d10 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23d20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
23d30 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
23d40 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
23d50 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
23d60 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
23d70 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
23d80 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
23d90 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
23da0 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
23db0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
23dc0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
23dd0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
23de0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
23df0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
23e00 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
23e10 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
23e20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
23e30 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
23e40 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
23e50 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
23e60 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
23e70 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
23e80 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
23e90 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
23ea0 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
23eb0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
23ec0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
23ed0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
23ee0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
23ef0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
23f00 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
23f10 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
23f20 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
23f30 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
23f40 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
23f50 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
23f60 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
23f70 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
23f80 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
23f90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
23fa0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
23fb0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
23fc0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
23fd0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
23fe0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
23ff0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24000 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24010 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
24020 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
24030 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
24040 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
24050 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
24060 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
24070 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
24080 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
24090 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
240a0 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
240b0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
240c0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
240d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
240e0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
240f0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
24100 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
24110 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
24120 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
24130 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
24140 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
24150 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
24160 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
24170 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
24180 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
24190 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
241a0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
241b0 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
241c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
241d0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
241e0 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
241f0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
24200 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
24210 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
24220 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
24230 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
24240 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
24250 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
24260 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
24270 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
24280 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
24290 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
242a0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
242b0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
242c0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
242d0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
242e0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
242f0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
24300 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
24310 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
24320 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
24330 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
24340 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
24350 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
24360 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
24370 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
24380 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
24390 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
243a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
243b0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
243c0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
243d0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
243e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
243f0 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
24400 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
24410 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
24420 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
24430 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
24440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
24450 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
24460 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
24470 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
24480 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
24490 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
244a0 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
244b0 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
244c0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
244d0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
244e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
244f0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
24500 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
24510 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
24520 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
24530 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
24540 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
24550 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
24560 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
24570 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
24580 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
24590 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
245a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
245b0 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
245c0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
245d0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
245e0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
245f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
24600 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
24610 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
24620 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
24630 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
24640 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
24650 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
24660 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
24670 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
24680 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
24690 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
246a0 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
246b0 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
246c0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
246d0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
246e0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
246f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
24700 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
24710 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
24720 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24730 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
24740 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
24750 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
24760 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
24770 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
24780 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
24790 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
247a0 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
247b0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
247c0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
247d0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
247e0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
247f0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24800 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
24810 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
24820 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
24830 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
24840 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
24850 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
24860 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
24870 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
24880 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
24890 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
248a0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
248b0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
248c0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
248d0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
248e0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
248f0 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
24900 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
24910 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
24920 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
24930 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
24940 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
24950 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
24960 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
24970 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
24980 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
24990 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
249a0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
249b0 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
249c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
249d0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
249e0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
249f0 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
24a00 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
24a10 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
24a20 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
24a30 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
24a40 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
24a50 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
24a60 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
24a70 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
24a80 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
24a90 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
24aa0 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
24ab0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
24ac0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
24ad0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
24ae0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
24af0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
24b00 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
24b10 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
24b20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
24b30 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
24b40 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
24b50 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
24b60 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
24b70 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
24b80 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
24b90 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
24ba0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
24bb0 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
24bc0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
24bd0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
24be0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
24bf0 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
24c00 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
24c10 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
24c20 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
24c30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
24c40 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
24c50 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
24c60 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
24c70 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
24c80 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
24c90 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
24ca0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
24cb0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
24cc0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
24cd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
24ce0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
24cf0 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sages.**.** ^If 
24d00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
24d10 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
24d20 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ll associated wi
24d30 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  th .** [database
24d40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66   connection] D f
24d50 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ailed, then the 
24d60 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
24d70 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  D) interface.** 
24d80 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
24d90 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
24da0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72  ] or [extended r
24db0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
24dc0 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c  that.** API call
24dd0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74  ..** If the most
24de0 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
24df0 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c   was successful,
24e00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
24e10 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
24e20 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
24e30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
24e40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
24e50 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
24e60 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
24e70 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
24e80 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
24e90 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
24ea0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
24eb0 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
24ec0 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
24ed0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
24ee0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
24ef0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
24f00 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
24f10 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
24f20 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
24f30 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
24f40 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
24f50 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
24f60 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
24f70 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
24f80 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
24f90 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
24fa0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
24fb0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
24fc0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
24fd0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
24fe0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
24ff0 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
25000 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
25010 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
25020 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
25030 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
25040 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
25050 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
25060 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
25070 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
25080 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
25090 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
250a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
250b0 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
250c0 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
250d0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
250e0 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
250f0 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
25100 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
25110 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
25120 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
25130 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
25140 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
25150 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
25160 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
25170 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
25180 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
25190 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
251a0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
251b0 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
251c0 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
251d0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
251e0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
251f0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
25200 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
25210 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
25220 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
25230 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
25240 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
25250 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
25260 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
25270 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
25280 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
25290 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
252a0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
252b0 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
252c0 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
252d0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
252e0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
252f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25300 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
25310 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
25320 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
25330 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
25340 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
25350 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
25360 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
25370 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
25380 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
25390 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
253a0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
253b0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
253c0 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
253d0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
253e0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
253f0 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
25400 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
25410 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
25420 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
25430 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
25440 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25450 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
25460 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
25470 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
25480 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
25490 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
254a0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
254b0 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
254c0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
254d0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
254e0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
254f0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
25500 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
25510 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
25520 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
25530 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
25540 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
25550 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
25560 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
25570 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
25580 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
25590 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
255a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
255b0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
255c0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
255d0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
255e0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
255f0 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
25600 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
25610 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
25620 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25630 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
25640 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
25650 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
25660 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
25670 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
25680 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
25690 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
256a0 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
256b0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
256c0 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
256d0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
256e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
256f0 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
25700 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
25710 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
25720 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
25730 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
25740 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25750 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
25760 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
25770 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
25780 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
25790 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
257a0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
257b0 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
257c0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
257d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
257e0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
257f0 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
25800 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
25810 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
25820 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
25830 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
25840 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
25850 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
25860 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
25870 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
25880 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
25890 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
258a0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
258b0 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
258c0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
258d0 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
258e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
258f0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
25900 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
25910 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
25920 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
25930 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
25940 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
25950 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
25960 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
25970 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
25980 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
25990 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
259a0 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
259b0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
259c0 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
259d0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
259e0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
259f0 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
25a00 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
25a10 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
25a20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
25a30 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
25a40 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
25a50 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
25a60 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
25a70 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
25a80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
25a90 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
25aa0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
25ab0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
25ac0 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
25ad0 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
25ae0 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
25af0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
25b00 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
25b10 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
25b20 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
25b30 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
25b40 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
25b50 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
25b60 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
25b70 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
25b80 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
25b90 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
25ba0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
25bb0 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
25bc0 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
25bd0 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
25be0 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
25bf0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
25c00 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
25c10 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
25c20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
25c30 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
25c40 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
25c50 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
25c60 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
25c70 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
25c80 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
25c90 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
25ca0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
25cb0 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
25cc0 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
25cd0 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
25ce0 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
25cf0 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
25d00 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
25d10 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
25d20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25d30 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
25d40 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
25d50 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
25d60 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
25d70 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
25d80 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
25d90 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
25da0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
25db0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
25dc0 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
25dd0 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
25de0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
25df0 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
25e00 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
25e10 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
25e20 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
25e30 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
25e40 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
25e50 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
25e60 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
25e70 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
25e80 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
25e90 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
25ea0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
25eb0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
25ec0 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
25ed0 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
25ee0 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
25ef0 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
25f00 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
25f10 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
25f20 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
25f30 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
25f40 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
25f50 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
25f60 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
25f70 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
25f80 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
25f90 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
25fa0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
25fb0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
25fc0 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
25fd0 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
25fe0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
25ff0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
26000 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
26010 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
26020 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
26030 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
26040 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
26050 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
26060 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
26070 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
26080 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
26090 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
260a0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
260b0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
260c0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
260d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
260e0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
260f0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
26100 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
26110 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
26120 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
26130 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
26140 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
26150 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
26160 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
26170 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
26180 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
26190 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
261a0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
261b0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
261c0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
261d0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
261e0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
261f0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
26200 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
26210 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
26220 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
26230 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
26240 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
26250 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
26260 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
26270 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26280 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
26290 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
262a0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
262b0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
262c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
262d0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
262e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
262f0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
26300 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26310 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26320 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
26330 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
26340 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26350 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
26360 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26370 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
26380 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26390 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
263a0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
263b0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
263c0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
263d0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
263e0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
263f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
26400 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
26410 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
26420 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
26430 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
26440 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26450 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
26460 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26470 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
26480 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26490 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
264a0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
264b0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
264c0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
264d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
264e0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
264f0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26500 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
26510 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
26520 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26530 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
26540 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
26550 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
26560 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26570 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
26580 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26590 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
265a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
265b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
265c0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
265d0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
265e0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
265f0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
26600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
26610 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
26620 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
26630 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
26640 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
26650 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
26660 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
26670 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
26680 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26690 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
266a0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
266b0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
266c0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
266d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
266e0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
266f0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
26700 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26710 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
26720 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
26730 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
26740 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
26750 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26760 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
26770 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
26780 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
26790 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
267a0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
267b0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
267c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
267d0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
267e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
267f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26800 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
26810 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
26820 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
26830 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
26840 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26850 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
26860 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
26870 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26880 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
26890 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
268a0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
268b0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
268c0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
268d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
268e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
268f0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
26900 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
26910 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
26920 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
26930 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
26940 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
26950 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
26960 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26970 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
26980 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
26990 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
269a0 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
269b0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
269c0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
269d0 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
269e0 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
269f0 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
26a00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
26a10 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
26a20 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
26a30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26a40 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
26a50 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
26a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26a70 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
26a80 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
26a90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26aa0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
26ab0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
26ac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26ad0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
26ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
26af0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26b00 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
26b10 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
26b20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26b30 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
26b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26b50 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
26b60 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
26b70 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
26b80 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
26b90 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
26ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26bb0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
26bc0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
26bd0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
26be0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
26bf0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
26c00 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
26c10 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
26c20 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
26c30 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
26c40 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
26c50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
26c60 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
26c70 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
26c80 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
26c90 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
26ca0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
26cb0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
26cc0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
26cd0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
26ce0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
26cf0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
26d00 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
26d10 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
26d20 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
26d30 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
26d40 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
26d50 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
26d60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26d70 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
26d80 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
26d90 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
26da0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
26db0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
26dc0 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
26dd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
26de0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
26df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
26e00 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
26e10 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
26e20 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
26e30 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
26e40 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
26e50 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
26e60 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
26e70 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
26e80 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
26e90 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
26ea0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26eb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
26ec0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
26ed0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
26ee0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
26ef0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
26f00 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
26f10 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
26f20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
26f30 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
26f40 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
26f50 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
26f60 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
26f70 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
26f80 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
26f90 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
26fa0 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
26fb0 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
26fc0 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
26fd0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
26fe0 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
26ff0 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
27000 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
27010 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
27020 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
27030 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
27040 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
27050 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
27060 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
27070 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
27080 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
27090 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
270a0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
270b0 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
270c0 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
270d0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
270e0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
270f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
27100 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
27110 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
27120 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
27130 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
27140 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
27150 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
27160 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
27170 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
27180 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
27190 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
271a0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
271b0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
271c0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
271d0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
271e0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
271f0 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
27200 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
27210 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
27220 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
27230 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
27240 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
27250 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
27260 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
27270 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
27280 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
27290 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
272a0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
272b0 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
272c0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
272d0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
272e0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
272f0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
27300 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
27310 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
27320 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
27330 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
27340 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
27350 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
27360 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
27370 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
27380 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
27390 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
273a0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
273b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
273c0 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
273d0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
273e0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
273f0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
27400 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
27410 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
27420 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27430 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
27440 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
27450 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
27460 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
27470 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
27480 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
27490 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
274a0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
274b0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
274c0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
274d0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
274e0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
274f0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
27500 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
27510 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
27520 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
27530 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
27540 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
27550 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
27560 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
27570 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
27580 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
27590 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
275a0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
275b0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
275c0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
275d0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
275e0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
275f0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
27600 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
27610 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
27620 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
27630 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
27640 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27650 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
27660 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
27670 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
27680 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
27690 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
276a0 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
276b0 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
276c0 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
276d0 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
276e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
276f0 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
27700 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
27710 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
27720 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
27730 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
27740 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
27750 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
27760 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
27770 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
27780 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
27790 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
277a0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
277b0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
277c0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
277d0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
277e0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
277f0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
27800 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
27810 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
27820 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
27830 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
27840 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
27850 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
27860 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
27870 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
27880 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
27890 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
278a0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
278b0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
278c0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
278d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
278e0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
278f0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
27900 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
27910 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
27920 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
27930 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
27940 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
27950 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
27960 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
27970 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
27980 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
27990 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
279a0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
279b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
279c0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
279d0 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
279e0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
279f0 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
27a00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27a10 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
27a20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
27a30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
27a40 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
27a50 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
27a60 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
27a70 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
27a80 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
27a90 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
27aa0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
27ab0 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
27ac0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
27ad0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
27ae0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
27af0 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
27b00 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
27b10 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
27b20 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
27b30 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
27b40 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
27b50 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
27b60 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
27b70 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
27b80 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69  enabled..** </li
27b90 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
27ba0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
27bb0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
27bc0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
27bd0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
27be0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27bf0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
27c00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
27c10 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
27c20 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
27c30 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
27c40 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
27c50 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
27c60 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
27c70 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
27c80 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
27c90 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
27ca0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
27cb0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
27cc0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
27cd0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
27ce0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
27cf0 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
27d00 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
27d10 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
27d20 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
27d30 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
27d40 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
27d50 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
27d60 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
27d70 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27d80 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27d90 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27da0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27db0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27dc0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
27dd0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27de0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
27df0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
27e00 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
27e10 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
27e20 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
27e30 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
27e40 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
27e50 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
27e60 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
27e70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
27e80 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
27e90 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
27ea0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27eb0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27ec0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27ed0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
27ee0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
27ef0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27f00 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27f10 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27f20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27f30 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27f40 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27f50 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27f60 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
27f70 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27f80 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
27f90 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
27fa0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
27fb0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
27fc0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
27fd0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
27fe0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
27ff0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
28000 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
28010 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
28020 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
28030 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
28040 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
28050 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
28060 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
28070 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
28080 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
28090 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
280a0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
280b0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
280c0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
280d0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
280e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
280f0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
28100 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
28110 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
28120 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
28130 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
28140 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
28150 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
28160 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
28170 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
28180 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
28190 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
281a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
281b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
281c0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
281d0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
281e0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
281f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28200 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
28210 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
28220 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
28230 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
28240 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
28250 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
28260 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
28270 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
28280 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
28290 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
282a0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
282b0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
282c0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
282d0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
282e0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
282f0 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
28300 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
28310 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
28320 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
28330 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
28340 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
28350 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
28360 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
28370 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
28380 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
28390 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
283a0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
283b0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
283c0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
283d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
283e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
283f0 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
28400 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
28410 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
28420 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
28430 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
28440 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
28450 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
28460 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
28470 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
28480 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
28490 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
284a0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
284b0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
284c0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
284d0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
284e0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
284f0 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
28500 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
28510 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
28520 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
28530 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
28540 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
28550 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
28560 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
28570 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
28580 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
28590 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
285a0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
285b0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
285c0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
285d0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
285e0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
285f0 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
28600 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
28610 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
28620 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
28630 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
28640 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
28650 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
28660 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
28670 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
28680 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
28690 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
286a0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
286b0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
286c0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
286d0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
286e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
286f0 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
28700 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
28710 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
28720 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
28730 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
28740 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
28750 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
28760 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
28770 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28780 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
28790 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
287a0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
287b0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
287c0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
287d0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
287e0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
287f0 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
28800 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28810 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
28820 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
28830 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
28840 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
28850 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
28860 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
28870 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
28880 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
28890 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
288a0 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
288b0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
288c0 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
288d0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
288e0 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
288f0 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
28900 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
28910 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
28920 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
28930 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
28940 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
28950 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
28960 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
28970 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
28980 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
28990 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
289a0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
289b0 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
289c0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
289d0 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
289e0 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
289f0 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
28a00 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
28a10 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
28a20 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
28a30 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
28a40 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
28a50 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
28a60 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
28a70 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
28a80 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
28a90 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
28aa0 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
28ab0 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
28ac0 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
28ad0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
28ae0 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
28af0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28b00 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
28b10 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
28b20 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
28b30 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
28b40 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
28b50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28b60 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
28b70 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
28b80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28b90 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
28ba0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
28bb0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
28bc0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
28bd0 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
28be0 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
28bf0 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
28c00 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
28c10 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
28c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28c30 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
28c40 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
28c50 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
28c60 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
28c70 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
28c80 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
28c90 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
28ca0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
28cb0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
28cc0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
28cd0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
28ce0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28cf0 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
28d00 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
28d10 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
28d20 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
28d30 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
28d40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
28d50 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
28d60 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
28d70 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
28d80 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
28d90 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
28da0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
28db0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28dc0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
28dd0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
28de0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
28df0 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
28e00 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
28e10 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
28e20 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
28e30 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
28e40 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
28e50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28e60 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
28e70 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
28e80 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
28e90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28ea0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
28eb0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
28ec0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
28ed0 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
28ee0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
28ef0 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
28f00 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
28f10 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
28f20 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
28f30 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
28f40 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
28f50 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
28f60 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
28f70 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
28f80 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
28f90 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
28fa0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
28fb0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
28fc0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
28fd0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28fe0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
28ff0 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
29000 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
29010 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
29020 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
29030 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
29040 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
29050 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
29060 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
29070 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
29080 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
29090 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
290a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
290b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
290c0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
290d0 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
290e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
290f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
29100 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
29110 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
29120 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
29130 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
29140 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29150 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
29160 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
29170 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
29180 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
29190 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
291a0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
291b0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
291c0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
291d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
291e0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
291f0 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
29200 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
29210 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
29220 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
29230 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
29240 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
29250 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
29260 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
29270 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
29280 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
29290 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
292a0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
292b0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
292c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
292d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
292e0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
292f0 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
29300 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
29310 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
29320 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
29330 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
29340 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
29350 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
29360 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
29370 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
29380 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
29390 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
293a0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
293b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
293c0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
293d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
293e0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
293f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29400 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
29410 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
29420 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
29430 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
29440 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
29450 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
29460 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
29470 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
29480 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
29490 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
294a0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
294b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
294c0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
294d0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
294e0 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
294f0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
29500 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
29510 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
29520 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
29530 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
29540 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
29550 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
29560 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
29570 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
29580 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
29590 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
295a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
295b0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
295c0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
295d0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
295e0 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
295f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
29600 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
29610 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29620 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
29630 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
29640 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
29650 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
29660 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
29670 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
29680 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
29690 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
296a0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
296b0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
296c0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
296d0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
296e0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
296f0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
29700 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
29710 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
29720 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
29730 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
29740 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
29750 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
29760 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
29770 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
29780 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
29790 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
297a0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
297b0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
297c0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
297d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
297e0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
297f0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
29800 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29810 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
29820 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
29830 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
29840 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
29850 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
29860 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
29870 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
29880 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
29890 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
298a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
298b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
298c0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
298d0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
298e0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
298f0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
29900 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
29910 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
29920 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
29930 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
29940 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
29950 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
29960 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
29970 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
29980 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
29990 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
299a0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
299b0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
299c0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
299d0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
299e0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
299f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29a00 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
29a10 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
29a20 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
29a30 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
29a40 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
29a50 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
29a60 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
29a70 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
29a80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
29a90 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
29aa0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
29ab0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
29ac0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
29ad0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
29ae0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
29af0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
29b00 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
29b10 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
29b20 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
29b30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
29b40 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
29b50 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
29b60 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
29b70 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
29b80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
29b90 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
29ba0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
29bb0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
29bc0 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
29bd0 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
29be0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
29bf0 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
29c00 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
29c10 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
29c20 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
29c30 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
29c40 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
29c50 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
29c60 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
29c70 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
29c80 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
29c90 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
29ca0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
29cb0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
29cc0 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
29cd0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
29ce0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29cf0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
29d00 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
29d10 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
29d20 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
29d30 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
29d40 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
29d50 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
29d60 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
29d70 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
29d80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
29d90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
29da0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
29db0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
29dc0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
29dd0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
29de0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
29df0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
29e00 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
29e10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
29e20 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
29e30 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
29e40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29e50 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
29e60 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
29e70 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
29e80 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
29e90 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
29ea0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
29eb0 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
29ec0 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
29ed0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
29ee0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
29ef0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
29f00 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
29f10 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
29f20 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
29f30 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
29f40 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
29f50 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
29f60 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
29f70 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
29f80 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
29f90 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
29fa0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
29fb0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
29fc0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
29fd0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
29fe0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
29ff0 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2a000 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2a010 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2a020 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2a030 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2a040 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2a050 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2a060 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2a070 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2a080 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2a090 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2a0a0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2a0b0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2a0c0 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2a0d0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2a0e0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2a0f0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2a100 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2a110 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2a120 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2a130 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2a140 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2a150 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2a160 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2a170 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2a180 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2a190 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2a1a0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2a1b0 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2a1c0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2a1d0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2a1e0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2a1f0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2a200 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2a210 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2a220 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2a230 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2a240 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2a250 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2a260 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2a270 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2a280 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2a290 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2a2a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2a2b0 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2a2c0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2a2d0 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2a2e0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2a2f0 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2a300 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2a310 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a320 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2a330 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2a340 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2a350 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2a360 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2a370 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2a380 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2a390 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2a3a0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2a3b0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2a3c0 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2a3d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2a3e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2a3f0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2a400 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2a410 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2a420 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2a430 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2a440 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2a450 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2a460 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2a470 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2a480 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2a490 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2a4a0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2a4b0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2a4c0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2a4d0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2a4e0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2a4f0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2a500 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2a510 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2a520 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2a530 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2a540 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2a550 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2a560 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2a570 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2a580 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
2a590 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
2a5a0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2a5b0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2a5c0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
2a5d0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
2a5e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a5f0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
2a600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a610 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
2a620 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a630 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
2a640 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
2a650 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
2a660 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
2a670 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
2a680 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
2a690 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
2a6a0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
2a6b0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
2a6c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a6d0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2a6e0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
2a6f0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
2a700 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2a710 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
2a720 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
2a730 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
2a740 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
2a750 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
2a760 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
2a770 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
2a780 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
2a790 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2a7a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
2a7b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2a7c0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
2a7d0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
2a7e0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
2a7f0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
2a800 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54  g..** ^[SQLITE_T
2a810 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20  OOBIG] might be 
2a820 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2a830 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67  size of a string
2a840 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65   or BLOB.** exce
2a850 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73  eds limits impos
2a860 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
2a870 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2a880 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a  MIT_LENGTH]) or.
2a890 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c  ** [SQLITE_MAX_L
2a8a0 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c  ENGTH]..** ^[SQL
2a8b0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
2a8c0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
2a8d0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
2a8e0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2a8f0 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
2a900 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
2a910 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
2a920 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2a930 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2a940 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2a950 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2a960 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2a970 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
2a980 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a990 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2a9a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a9b0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
2a9c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2a9d0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
2a9e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2a9f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2aa00 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
2aa10 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2aa20 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  t void*, sqlite3
2aa30 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2aa40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aa50 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2aa60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2aa70 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2aa80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2aa90 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
2aaa0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
2aab0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2aac0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2aad0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
2aae0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2aaf0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2ab00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2ab10 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
2ab20 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
2ab30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ab40 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2ab50 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
2ab60 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2ab70 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2ab80 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
2ab90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2aba0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2abb0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2abc0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2abd0 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
2abe0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2abf0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
2ac00 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2ac10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ac20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2ac30 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
2ac40 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69  har encoding);.i
2ac50 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ac60 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2ac70 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2ac80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2ac90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2aca0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
2acb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2acc0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
2acd0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2ace0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2acf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2ad00 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
2ad10 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
2ad20 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
2ad30 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
2ad40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ad50 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
2ad60 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
2ad70 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
2ad80 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
2ad90 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
2ada0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
2adb0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
2adc0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
2add0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
2ade0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
2adf0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
2ae00 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
2ae10 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
2ae20 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2ae30 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
2ae40 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2ae50 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
2ae60 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
2ae70 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
2ae80 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
2ae90 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
2aea0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
2aeb0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
2aec0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
2aed0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2aee0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
2aef0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
2af00 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
2af10 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
2af20 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2af30 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2af40 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2af50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2af60 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2af70 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2af80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2af90 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
2afa0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2afb0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
2afc0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2afd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2afe0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
2aff0 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
2b000 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2b010 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2b020 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2b030 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2b040 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2b050 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2b060 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2b070 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2b080 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2b090 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2b0a0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2b0b0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2b0c0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2b0d0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2b0e0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2b0f0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2b100 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2b110 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2b120 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2b130 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2b140 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2b150 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2b160 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2b170 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2b180 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2b190 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2b1a0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2b1b0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2b1c0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2b1d0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2b1e0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2b1f0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2b200 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2b210 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2b220 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2b230 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2b240 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2b250 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2b260 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2b270 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2b280 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2b290 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2b2a0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2b2b0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2b2c0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2b2d0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2b2e0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2b2f0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2b300 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2b310 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2b320 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2b330 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2b340 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2b350 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b360 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b370 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2b380 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2b390 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b3a0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2b3b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b3c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2b3d0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2b3e0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
2b3f0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
2b400 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b410 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b420 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
2b430 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
2b440 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
2b450 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
2b460 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
2b470 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
2b480 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
2b490 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
2b4a0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
2b4b0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
2b4c0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
2b4d0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2b4e0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2b4f0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
2b500 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
2b510 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
2b520 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
2b530 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
2b540 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
2b550 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
2b560 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
2b570 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
2b580 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
2b590 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
2b5a0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
2b5b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2b5c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2b5d0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2b5e0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2b5f0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2b600 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b610 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2b620 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2b630 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2b640 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2b650 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b660 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
2b670 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
2b680 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
2b690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2b6a0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
2b6b0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
2b6c0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2b6d0 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
2b6e0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
2b6f0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
2b700 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
2b710 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
2b720 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2b730 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
2b740 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b750 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
2b760 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
2b770 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
2b780 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
2b790 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b7a0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
2b7b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2b7c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b7d0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
2b7e0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2b7f0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2b800 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2b810 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2b820 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
2b830 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
2b840 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b850 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
2b860 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
2b870 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
2b880 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
2b890 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
2b8a0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
2b8b0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
2b8c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b8d0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2b8e0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
2b8f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2b900 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2b910 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2b920 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
2b930 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
2b940 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
2b950 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2b960 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
2b970 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
2b980 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
2b990 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b9a0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
2b9b0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
2b9c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2b9d0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
2b9e0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2b9f0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2ba00 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
2ba10 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
2ba20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2ba30 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
2ba40 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2ba50 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
2ba60 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2ba70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2ba80 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
2ba90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2baa0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
2bab0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
2bac0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
2bad0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2bae0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
2baf0 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
2bb00 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2bb10 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
2bb20 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2bb30 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
2bb40 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
2bb50 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
2bb60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2bb70 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
2bb80 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
2bb90 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2bba0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2bbb0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2bbc0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2bbd0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2bbe0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2bbf0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2bc00 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2bc10 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
2bc20 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2bc30 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
2bc40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bc50 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
2bc60 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
2bc70 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
2bc80 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
2bc90 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
2bca0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
2bcb0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
2bcc0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
2bcd0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
2bce0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
2bcf0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
2bd00 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2bd10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
2bd20 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
2bd30 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
2bd40 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
2bd50 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
2bd60 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
2bd70 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
2bd80 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
2bd90 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
2bda0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
2bdb0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
2bdc0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
2bdd0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
2bde0 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
2bdf0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
2be00 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
2be10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2be20 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
2be30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2be40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2be50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2be60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2be70 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2be80 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2be90 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2bea0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2beb0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2bec0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2bed0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2bee0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2bef0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2bf00 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2bf10 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2bf20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2bf30 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2bf40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2bf50 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2bf60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2bf70 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2bf80 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2bf90 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2bfa0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2bfb0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2bfc0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2bfd0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2bfe0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2bff0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2c000 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2c010 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2c020 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2c030 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2c040 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2c050 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2c060 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2c070 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2c080 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c090 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2c0a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2c0b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2c0c0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2c0d0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2c0e0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2c0f0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2c100 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c110 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2c120 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2c130 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2c140 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2c150 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2c160 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2c170 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2c180 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2c190 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2c1a0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2c1b0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2c1c0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2c1d0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2c1e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2c1f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2c200 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2c210 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c220 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2c230 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2c240 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2c250 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2c260 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2c270 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2c280 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2c290 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2c2a0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2c2b0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2c2c0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2c2d0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2c2e0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2c2f0 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2c300 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2c310 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2c320 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2c330 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2c340 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2c350 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2c360 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2c370 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2c380 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2c390 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2c3a0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2c3b0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2c3c0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2c3d0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2c3e0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2c3f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2c400 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2c410 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2c420 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2c430 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2c440 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2c450 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2c460 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2c470 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2c480 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2c490 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2c4a0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2c4b0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2c4c0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2c4d0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2c4e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2c4f0 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2c500 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2c510 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2c520 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2c530 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2c540 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2c550 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2c560 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2c570 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2c580 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2c590 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2c5a0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2c5b0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2c5c0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2c5d0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2c5e0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2c5f0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2c600 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2c610 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2c620 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2c630 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2c640 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2c650 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2c660 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2c670 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2c680 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2c690 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2c6a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2c6b0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2c6c0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2c6d0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2c6e0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2c6f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2c700 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2c710 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2c720 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2c730 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2c740 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
2c750 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2c760 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2c770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2c780 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2c790 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2c7a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c7b0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
2c7c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2c7d0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2c7e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c7f0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
2c800 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2c810 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2c820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2c830 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
2c840 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2c850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2c860 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
2c870 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
2c880 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
2c890 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2c8a0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2c8b0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
2c8c0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
2c8d0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
2c8e0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
2c8f0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2c900 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
2c910 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
2c920 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
2c930 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
2c940 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2c950 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
2c960 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
2c970 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
2c980 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2c990 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2c9a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2c9b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2c9c0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2c9d0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2c9e0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2c9f0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2ca00 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2ca10 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2ca20 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2ca30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2ca40 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2ca50 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2ca60 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2ca70 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2ca80 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2ca90 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2caa0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2cab0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2cac0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2cad0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2cae0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2caf0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2cb00 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2cb10 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2cb20 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2cb30 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2cb40 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2cb50 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2cb60 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2cb70 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2cb80 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2cb90 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2cba0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2cbb0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2cbc0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2cbd0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2cbe0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2cbf0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2cc00 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2cc10 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2cc20 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2cc30 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2cc40 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2cc50 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2cc60 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2cc70 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2cc80 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2cc90 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2cca0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2ccb0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2ccc0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2ccd0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
2cce0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ccf0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2cd00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2cd10 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2cd20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2cd30 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2cd40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2cd50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cd60 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2cd70 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2cd80 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2cd90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2cda0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2cdb0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2cdc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cdd0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2cde0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2cdf0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2ce00 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2ce10 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2ce20 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2ce30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2ce40 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2ce50 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2ce60 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2ce70 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2ce80 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2ce90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2cea0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2ceb0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2cec0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2ced0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2cee0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2cef0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2cf00 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2cf10 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2cf20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2cf30 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2cf40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cf50 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2cf60 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2cf70 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2cf80 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2cf90 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2cfa0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2cfb0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2cfc0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2cfd0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2cfe0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2cff0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2d000 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2d010 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2d020 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2d030 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2d040 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2d050 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2d060 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2d070 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2d080 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2d090 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2d0a0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2d0b0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2d0c0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2d0d0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2d0e0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2d0f0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2d100 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2d110 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2d120 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2d130 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2d140 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2d150 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2d160 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2d170 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2d180 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2d190 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2d1a0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2d1b0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2d1c0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2d1d0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2d1e0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2d1f0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2d200 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2d210 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2d220 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2d230 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2d240 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2d250 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2d260 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2d270 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2d280 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2d290 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2d2a0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2d2b0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2d2c0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2d2d0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2d2e0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2d2f0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2d300 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2d310 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2d320 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2d330 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2d340 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2d350 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2d360 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2d370 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2d380 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2d390 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2d3a0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2d3b0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2d3c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2d3d0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2d3e0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2d3f0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2d400 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2d410 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2d420 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2d430 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2d440 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2d450 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2d460 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2d470 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2d480 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2d490 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2d4a0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2d4b0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2d4c0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2d4d0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2d4e0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2d4f0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2d500 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2d510 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2d520 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2d530 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2d540 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2d550 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2d560 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2d570 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2d580 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2d590 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2d5a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2d5b0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2d5c0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2d5d0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2d5e0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2d5f0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2d600 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2d610 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2d620 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2d630 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2d640 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2d650 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2d660 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2d670 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2d680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d690 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2d6a0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2d6b0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2d6c0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2d6d0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2d6e0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2d6f0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2d700 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2d710 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2d720 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2d730 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2d740 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2d750 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2d760 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2d770 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2d780 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2d790 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2d7a0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2d7b0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2d7c0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2d7d0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2d7e0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2d7f0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2d800 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2d810 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2d820 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2d830 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2d840 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2d850 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2d860 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2d870 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2d880 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2d890 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2d8a0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2d8b0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2d8c0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2d8d0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2d8e0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2d8f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2d900 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2d910 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2d920 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2d930 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2d940 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2d950 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2d960 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2d970 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2d980 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2d990 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2d9a0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2d9b0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2d9c0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2d9d0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2d9e0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2d9f0 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2da00 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2da10 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2da20 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2da30 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2da40 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2da50 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2da60 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2da70 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2da80 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2da90 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2daa0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2dab0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2dac0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2dad0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2dae0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2daf0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2db00 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2db10 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2db20 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2db30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2db40 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2db50 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2db60 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2db70 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2db80 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2db90 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2dba0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2dbb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2dbc0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2dbd0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2dbe0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2dbf0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2dc00 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2dc10 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2dc20 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2dc30 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2dc40 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2dc50 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2dc60 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2dc70 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2dc80 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2dc90 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2dca0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2dcb0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2dcc0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2dcd0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2dce0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2dcf0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2dd00 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2dd10 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2dd20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2dd30 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2dd40 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2dd50 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2dd60 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2dd70 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2dd80 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2dd90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2dda0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2ddb0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2ddc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ddd0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2dde0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2ddf0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2de00 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2de10 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2de20 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2de30 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2de40 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2de50 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2de60 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2de70 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2de80 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2de90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2dea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2deb0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2dec0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2ded0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2dee0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2def0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2df00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2df10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2df20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2df30 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2df40 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2df50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2df60 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2df70 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2df80 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2df90 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2dfa0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2dfb0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2dfc0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2dfd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2dfe0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2dff0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2e000 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2e010 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2e020 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2e030 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2e040 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2e050 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2e060 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2e070 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2e080 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2e090 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2e0a0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2e0b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2e0c0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2e0d0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2e0e0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2e0f0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2e100 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2e110 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2e120 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2e130 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2e140 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2e150 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2e160 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2e170 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2e180 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2e190 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2e1a0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2e1b0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2e1c0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2e1d0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2e1e0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2e1f0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2e200 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2e210 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2e220 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e230 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2e240 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2e250 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2e260 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2e270 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2e280 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2e290 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2e2a0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2e2b0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2e2c0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2e2d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2e2e0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2e2f0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2e300 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2e310 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2e320 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2e330 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2e340 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2e350 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2e360 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2e370 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2e380 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2e390 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2e3a0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2e3b0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2e3c0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2e3d0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2e3e0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2e3f0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2e400 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2e410 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2e420 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2e430 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2e440 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2e450 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2e460 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2e470 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2e480 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2e490 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2e4a0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2e4b0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2e4c0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2e4d0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2e4e0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2e4f0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2e500 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2e510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2e520 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2e530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2e540 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2e550 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2e560 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2e570 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2e580 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2e590 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2e5a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2e5b0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2e5c0 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2e5d0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2e5e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2e5f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2e600 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2e610 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2e620 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2e630 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2e640 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2e650 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2e660 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2e670 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e680 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2e690 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2e6a0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2e6b0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2e6c0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2e6d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e6e0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2e6f0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2e700 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2e710 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2e720 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2e730 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2e740 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2e750 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2e760 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2e770 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2e780 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2e790 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2e7a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2e7b0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2e7c0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2e7d0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2e7e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2e7f0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2e800 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2e810 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2e820 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2e830 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2e840 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2e850 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2e860 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2e870 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2e880 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2e890 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2e8a0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2e8b0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2e8c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2e8d0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2e8e0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2e8f0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2e900 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e910 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2e920 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2e930 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2e940 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2e950 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2e960 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2e970 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2e980 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2e990 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e9a0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2e9b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2e9c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2e9d0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2e9e0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2e9f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2ea00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2ea10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ea20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2ea30 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2ea40 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2ea50 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2ea60 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2ea70 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2ea80 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2ea90 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2eaa0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2eab0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2eac0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ead0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2eae0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2eaf0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2eb00 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2eb10 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2eb20 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2eb30 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2eb40 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2eb50 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2eb60 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2eb70 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2eb80 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2eb90 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2eba0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2ebb0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2ebc0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2ebd0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2ebe0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2ebf0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2ec00 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2ec10 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2ec20 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2ec30 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2ec40 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2ec50 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2ec60 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2ec70 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2ec80 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2ec90 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2eca0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2ecb0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2ecc0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2ecd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ece0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2ecf0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2ed00 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2ed10 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ed20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2ed30 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2ed40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ed50 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2ed60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ed70 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2ed80 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2ed90 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2eda0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2edb0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2edc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2edd0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2ede0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2edf0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2ee00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2ee10 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2ee20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2ee30 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2ee40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2ee50 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2ee60 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2ee70 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2ee80 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2ee90 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2eea0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2eeb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2eec0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2eed0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2eee0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2eef0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ef00 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2ef10 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2ef20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2ef30 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2ef40 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2ef50 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ef60 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2ef70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2ef80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ef90 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2efa0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2efb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2efc0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2efd0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2efe0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2eff0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2f000 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2f010 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2f020 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2f030 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2f040 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2f050 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2f060 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f070 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2f080 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2f090 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2f0a0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2f0b0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2f0c0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2f0d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f0e0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2f0f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2f100 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2f110 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f120 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2f130 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2f140 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2f150 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2f160 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2f170 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f180 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f190 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2f1a0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2f1b0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2f1c0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2f1d0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2f1e0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2f1f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2f200 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f210 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2f220 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f230 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2f240 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2f250 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2f260 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2f270 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2f280 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2f290 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2f2a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2f2b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f2c0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2f2d0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2f2e0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2f2f0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2f300 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2f310 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2f320 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2f330 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2f340 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2f350 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2f360 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2f370 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2f380 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2f390 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2f3a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f3b0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2f3c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2f3d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2f3e0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2f3f0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2f400 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2f410 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2f420 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2f430 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2f440 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2f450 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2f460 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2f470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2f480 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2f490 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2f4a0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2f4b0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2f4c0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2f4d0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2f4e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2f4f0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2f500 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2f510 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2f520 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2f530 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2f540 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2f550 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2f560 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2f570 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2f580 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2f590 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2f5a0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2f5b0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2f5c0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2f5d0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2f5e0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2f5f0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2f600 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2f610 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2f620 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2f630 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2f640 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2f650 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2f660 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2f670 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2f680 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2f690 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2f6a0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2f6b0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2f6c0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2f6d0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2f6e0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2f6f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2f700 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2f710 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2f720 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2f730 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2f740 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2f750 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2f760 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2f770 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
2f780 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2f790 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2f7a0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2f7b0 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
2f7c0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2f7d0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2f7e0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2f7f0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2f800 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
2f810 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
2f820 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
2f830 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2f840 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2f850 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
2f860 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2f870 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2f880 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
2f890 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
2f8a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2f8b0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2f8c0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2f8d0 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2f8e0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2f8f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2f900 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2f910 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2f920 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2f930 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2f940 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
2f950 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
2f960 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
2f970 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2f980 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2f990 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2f9a0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2f9b0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2f9c0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
2f9d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2f9e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
2f9f0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
2fa00 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2fa10 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2fa20 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2fa30 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2fa40 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2fa50 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2fa60 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2fa70 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2fa80 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2fa90 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
2faa0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
2fab0 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
2fac0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2fad0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
2fae0 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
2faf0 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
2fb00 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
2fb10 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
2fb20 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
2fb30 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
2fb40 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
2fb50 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
2fb60 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
2fb70 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
2fb80 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
2fb90 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
2fba0 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
2fbb0 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
2fbc0 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
2fbd0 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
2fbe0 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
2fbf0 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
2fc00 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
2fc10 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
2fc20 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
2fc30 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
2fc40 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
2fc50 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2fc60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2fc70 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
2fc80 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
2fc90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2fca0 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
2fcb0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2fcc0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
2fcd0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
2fce0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
2fcf0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
2fd00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
2fd10 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2fd20 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2fd30 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
2fd40 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
2fd50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2fd60 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2fd70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2fd80 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
2fd90 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
2fda0 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
2fdb0 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
2fdc0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
2fdd0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2fde0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2fdf0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
2fe00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fe10 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
2fe20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2fe30 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2fe40 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2fe50 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2fe60 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2fe70 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
2fe80 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2fe90 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2fea0 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
2feb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fec0 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
2fed0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fee0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
2fef0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2ff00 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2ff10 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
2ff20 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
2ff30 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
2ff40 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
2ff50 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
2ff60 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
2ff70 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
2ff80 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
2ff90 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
2ffa0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
2ffb0 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
2ffc0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
2ffd0 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
2ffe0 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
2fff0 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
30000 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
30010 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
30020 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
30030 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
30040 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
30050 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
30060 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
30070 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
30080 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
30090 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
300a0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
300b0 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
300c0 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
300d0 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
300e0 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
300f0 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
30100 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
30110 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
30120 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
30130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30140 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
30150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30160 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
30170 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
30180 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
30190 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
301a0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
301b0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
301c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
301d0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
301e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
301f0 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
30200 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
30210 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
30220 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
30230 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
30240 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30250 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
30260 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30270 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
30280 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
30290 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
302a0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
302b0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
302c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
302d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
302e0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
302f0 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
30300 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
30310 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
30320 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
30330 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
30340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
30350 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
30360 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
30370 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
30380 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
30390 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
303a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
303b0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
303c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
303d0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
303e0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
303f0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
30400 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
30410 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
30420 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
30430 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
30440 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
30450 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
30460 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
30470 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
30480 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
30490 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
304a0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
304b0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
304c0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
304d0 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
304e0 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
304f0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
30500 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
30510 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
30520 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
30530 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
30540 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
30550 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
30560 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
30570 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
30580 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
30590 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
305a0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
305b0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
305c0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
305d0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
305e0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
305f0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
30600 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
30610 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
30620 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
30630 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
30640 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
30650 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
30660 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
30670 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
30680 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
30690 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
306a0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
306b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
306c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
306d0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
306e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
306f0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
30700 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
30710 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30720 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
30730 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
30740 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
30750 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30760 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
30770 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
30780 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30790 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
307a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
307b0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
307c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
307d0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
307e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
307f0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
30800 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30810 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30830 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30840 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
30850 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30860 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
30870 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
30880 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
30890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
308a0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
308b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
308c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
308d0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
308e0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
308f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
30900 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
30910 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
30920 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
30930 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30940 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
30950 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
30960 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
30970 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
30980 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
30990 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
309a0 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
309b0 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
309c0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
309d0 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
309e0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
309f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
30a00 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
30a10 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
30a20 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
30a30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
30a40 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
30a50 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
30a60 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
30a70 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
30a80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30a90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
30aa0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
30ab0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
30ac0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
30ad0 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
30ae0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30af0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
30b00 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
30b10 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
30b20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
30b30 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
30b40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
30b50 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
30b60 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
30b70 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
30b80 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
30b90 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
30ba0 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
30bb0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
30bc0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
30bd0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
30be0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
30bf0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
30c00 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
30c10 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
30c20 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
30c30 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
30c40 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
30c50 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
30c60 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
30c70 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
30c80 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
30c90 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
30ca0 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
30cb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30cc0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
30cd0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
30ce0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
30cf0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
30d00 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
30d10 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
30d20 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
30d30 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
30d40 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
30d50 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
30d60 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
30d70 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  ruption..*/.int 
30d80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30d90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
30da0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
30db0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
30dc0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
30dd0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
30de0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
30df0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
30e00 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
30e10 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
30e20 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
30e30 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
30e40 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
30e50 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
30e60 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
30e70 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
30e80 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
30e90 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
30ea0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
30eb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
30ec0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
30ed0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
30ee0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
30ef0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
30f00 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
30f10 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
30f20 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
30f30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30f40 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
30f50 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
30f60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30f70 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
30f80 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
30f90 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
30fa0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
30fb0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
30fc0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
30fd0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
30fe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30ff0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
31000 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
31010 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
31020 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
31030 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
31040 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
31050 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
31060 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
31070 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
31080 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
31090 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
310a0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
310b0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
310c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
310d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
310e0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
310f0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
31100 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
31110 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
31120 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
31130 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
31140 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
31150 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
31160 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
31170 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
31180 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
31190 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
311a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
311b0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
311c0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
311d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
311e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
311f0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
31200 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
31210 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
31220 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
31230 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
31240 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
31250 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31260 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
31270 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
31280 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31290 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
312a0 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
312b0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
312c0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
312d0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
312e0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
312f0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
31300 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
31310 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
31320 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
31330 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
31340 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
31350 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
31360 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
31370 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
31380 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
31390 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
313a0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
313b0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
313c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
313d0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
313e0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
313f0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
31400 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
31410 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
31420 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
31430 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
31440 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
31450 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
31460 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31470 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
31480 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
31490 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
314a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
314b0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
314c0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
314d0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
314e0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
314f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
31500 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31510 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
31520 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
31530 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
31540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
31550 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
31560 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
31570 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
31580 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
31590 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
315a0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
315b0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
315c0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
315d0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
315e0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
315f0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
31600 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
31610 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
31620 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
31630 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
31640 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
31650 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
31660 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
31670 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
31680 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
31690 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
316a0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
316b0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
316c0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
316d0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
316e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
316f0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
31700 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
31710 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
31720 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
31730 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31740 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
31750 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
31760 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
31770 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
31780 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
31790 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
317a0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
317b0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
317c0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
317d0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
317e0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
317f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
31800 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
31810 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
31820 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
31830 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
31840 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
31850 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
31860 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
31870 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
31880 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
31890 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
318a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
318b0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
318c0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
318d0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
318e0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
318f0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
31900 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
31910 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
31920 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
31930 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
31940 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
31950 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
31960 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31970 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
31980 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
31990 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
319a0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
319b0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
319c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
319d0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
319e0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
319f0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
31a00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31a10 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
31a20 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
31a30 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
31a40 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
31a50 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
31a60 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
31a70 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
31a80 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
31a90 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
31aa0 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
31ab0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
31ac0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
31ad0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
31ae0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
31af0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
31b00 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
31b10 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
31b20 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
31b30 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
31b40 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
31b50 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
31b60 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
31b70 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
31b80 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
31b90 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
31ba0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
31bb0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
31bc0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
31bd0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
31be0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
31bf0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
31c00 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
31c10 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
31c20 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
31c30 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
31c40 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
31c50 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
31c60 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
31c70 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
31c80 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
31c90 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
31ca0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
31cb0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
31cc0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
31cd0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
31ce0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
31cf0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
31d00 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
31d10 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
31d20 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
31d30 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
31d40 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
31d50 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
31d60 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
31d70 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
31d80 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
31d90 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
31da0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
31db0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
31dc0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
31dd0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
31de0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
31df0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
31e00 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
31e10 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
31e20 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
31e30 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
31e40 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
31e50 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
31e60 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
31e70 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
31e80 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
31e90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
31ea0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
31eb0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
31ec0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
31ed0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
31ee0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
31ef0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
31f00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
31f10 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
31f20 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
31f30 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
31f40 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
31f50 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
31f60 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
31f70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
31f80 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
31f90 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
31fa0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
31fb0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
31fc0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
31fd0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
31fe0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
31ff0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
32000 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
32010 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
32020 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
32030 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
32040 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
32050 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32060 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
32070 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
32080 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
32090 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
320a0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
320b0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
320c0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
320d0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
320e0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
320f0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
32100 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
32110 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
32120 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
32130 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
32140 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
32150 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
32160 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
32170 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32180 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
32190 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
321a0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
321b0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
321c0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
321d0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
321e0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
321f0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
32200 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
32210 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
32220 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
32230 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
32240 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
32250 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32260 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
32270 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
32280 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
32290 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
322a0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
322b0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
322c0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
322d0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
322e0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
322f0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
32300 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
32310 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
32320 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
32330 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
32340 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32350 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
32360 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
32370 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
32380 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
32390 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
323a0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
323b0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
323c0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
323d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
323e0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
323f0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
32400 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
32410 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
32420 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
32430 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
32440 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
32450 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
32460 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
32470 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
32480 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
32490 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
324a0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
324b0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
324c0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
324d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
324e0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
324f0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
32500 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
32510 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
32520 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
32530 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
32540 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
32550 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
32560 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
32570 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
32580 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
32590 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
325a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
325b0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
325c0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
325d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
325e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
325f0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
32600 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
32610 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
32620 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
32630 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
32640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32650 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
32660 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
32670 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
32680 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
32690 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
326a0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
326b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
326c0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
326d0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
326e0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
326f0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
32700 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
32710 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
32720 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
32730 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32740 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32750 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
32760 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32770 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32780 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32790 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
327a0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
327b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
327c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
327d0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
327e0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
327f0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
32800 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
32810 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
32820 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
32830 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
32840 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32850 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32860 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
32870 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32880 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32890 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
328a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
328b0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
328c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
328d0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
328e0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
328f0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
32900 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
32910 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
32920 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
32930 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
32940 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
32950 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
32960 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
32970 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
32980 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
32990 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
329a0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
329b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
329c0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
329d0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
329e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
329f0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
32a00 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
32a10 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
32a20 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
32a30 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
32a40 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
32a50 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
32a60 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
32a70 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
32a80 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20          1    /* 
32a90 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35  IMP: R-37514-355
32aa0 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  66 */.#define SQ
32ab0 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
32ac0 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a      2    /* IMP:
32ad0 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a   R-03371-37637 *
32ae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32af0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
32b00 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35  3    /* IMP: R-5
32b10 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64  1971-34154 */.#d
32b20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
32b30 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
32b40 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
32b50 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
32b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
32b70 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
32b80 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
32b90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32ba0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
32bb0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
32bc0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
32bd0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
32be0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
32bf0 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
32c00 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
32c10 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
32c20 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
32c30 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
32c40 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
32c50 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
32c60 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
32c70 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
32c80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32c90 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
32ca0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
32cb0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32cc0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32cd0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
32ce0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
32cf0 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
32d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32d10 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
32d20 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
32d30 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
32d40 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
32d50 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
32d60 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
32d70 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
32d80 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
32d90 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
32da0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
32db0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
32dc0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
32dd0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
32de0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
32df0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
32e00 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
32e10 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65  s.  To encourage
32e20 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20   programmers to 
32e30 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66  avoid.** these f
32e40 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c  unctions, we wil
32e50 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68  l not explain wh
32e60 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
32e70 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
32e80 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
32e90 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
32ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
32eb0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
32ec0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
32ed0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
32ee0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
32ef0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
32f00 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
32f10 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
32f20 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
32f30 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
32f40 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
32f50 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
32f60 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
32f70 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
32f80 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
32f90 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
32fa0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
32fb0 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
32fc0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
32fd0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
32fe0 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
32ff0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
33000 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20  t64,int),.      
33010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33020 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
33030 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
33040 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
33050 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
33060 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
33070 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
33080 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
33090 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
330a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
330b0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
330c0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
330d0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
330e0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
330f0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
33100 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
33110 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
33120 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
33130 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
33140 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
33150 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
33160 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
33170 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
33180 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
33190 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
331a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
331b0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
331c0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
331d0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
331e0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
331f0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
33200 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
33210 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
33220 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
33230 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
33240 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33250 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
33260 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
33270 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33280 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
33290 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
332a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
332b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
332c0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
332d0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
332e0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
332f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
33300 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
33310 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
33320 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
33330 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33340 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
33350 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
33360 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
33370 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
33380 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
33390 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
333a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
333b0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
333c0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
333d0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
333e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
333f0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
33400 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
33410 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74   that these rout
33420 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
33430 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
33440 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33450 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
33460 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
33470 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
33480 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
33490 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
334a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
334b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
334c0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
334d0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
334e0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
334f0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
33500 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
33510 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
33520 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
33530 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
33540 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33550 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
33560 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
33570 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
33580 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
33590 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
335a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
335b0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
335c0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
335d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
335e0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
335f0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
33600 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
33610 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
33620 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
33630 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
33640 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
33650 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
33660 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
33670 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
33680 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
33690 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
336a0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
336b0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
336c0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
336d0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
336e0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
336f0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
33700 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
33710 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
33720 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
33730 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
33740 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
33750 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
33760 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
33770 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
33780 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
33790 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
337a0 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
337b0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
337c0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
337d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
337e0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
337f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
33800 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
33810 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
33820 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
33830 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
33840 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
33850 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
33860 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
33870 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
33880 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
33890 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
338a0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
338b0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
338c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
338d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
338e0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
338f0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
33900 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
33910 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
33920 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
33930 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
33940 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
33950 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
33960 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
33970 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
33980 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
33990 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
339a0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
339b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
339c0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
339d0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
339e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
339f0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
33a00 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
33a10 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
33a20 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
33a30 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
33a40 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
33a50 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
33a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33a70 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33a80 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
33a90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33aa0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
33ab0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
33ac0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33ad0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
33ae0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
33af0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
33b00 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
33b10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
33b20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
33b30 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
33b40 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
33b50 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
33b60 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
33b70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
33b80 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
33b90 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
33ba0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
33bb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
33bc0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
33bd0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
33be0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
33bf0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
33c00 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
33c10 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
33c20 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
33c30 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
33c40 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
33c50 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
33c60 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
33c70 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
33c80 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
33c90 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
33ca0 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
33cb0 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
33cc0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
33cd0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
33ce0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
33cf0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
33d00 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
33d10 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
33d20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33d30 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
33d40 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
33d50 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
33d60 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
33d70 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
33d80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33d90 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
33da0 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
33db0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
33dc0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
33dd0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
33de0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
33df0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
33e00 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
33e10 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
33e20 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
33e30 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
33e40 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
33e50 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
33e60 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
33e70 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
33e80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
33e90 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
33ea0 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
33eb0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
33ec0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
33ed0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
33ee0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33ef0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
33f00 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
33f10 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
33f20 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
33f30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33f40 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33f50 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
33f60 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
33f70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20  ointer .** when 
33f80 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20  first called if 
33f90 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
33fa0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
33fb0 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a  or if a memory.*
33fc0 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  * allocate error
33fd0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
33fe0 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
33ff0 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
34000 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
34010 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
34020 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
34030 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
34040 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
34050 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
34060 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
34070 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
34080 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
34090 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
340a0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
340b0 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
340c0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
340d0 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
340e0 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
340f0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
34100 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20  tion.)^  Within 
34110 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
34120 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f  ack, it is custo
34130 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e  mary to set.** N
34140 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73  =0 in calls to s
34150 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34160 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f  _context(C,N) so
34170 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69   that no .** poi
34180 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c  ntless memory al
34190 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e  locations occur.
341a0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
341b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
341c0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
341d0 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
341e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
341f0 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
34200 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
34210 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
34220 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
34230 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
34240 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
34250 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
34260 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
34270 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
34280 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
34290 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
342a0 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
342b0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
342c0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
342d0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
342e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
342f0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
34300 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
34310 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
34320 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
34330 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
34340 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
34350 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
34360 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34370 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
34380 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34390 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
343a0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
343b0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
343c0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
343d0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
343e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
343f0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
34400 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
34410 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
34420 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
34430 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
34440 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
34450 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34460 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
34470 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34480 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
34490 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
344a0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
344b0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
344c0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
344d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
344e0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
344f0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
34500 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
34510 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
34520 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34530 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
34540 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
34550 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
34560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34580 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
34590 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
345a0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
345b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
345c0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
345d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
345e0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
345f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
34600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34610 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
34620 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
34630 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
34640 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
34650 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
34660 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
34670 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
34680 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
34690 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
346a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
346b0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
346c0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
346d0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
346e0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
346f0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
34700 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
34710 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
34720 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
34730 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
34740 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
34750 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
34760 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
34770 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
34780 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
34790 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
347a0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
347b0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
347c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
347d0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
347e0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
347f0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
34800 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
34810 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
34820 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
34830 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
34840 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
34850 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
34860 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
34870 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
34880 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
34890 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
348a0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
348b0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
348c0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
348d0 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
348e0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
348f0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74  ted with the pat
34900 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a  tern string.  .*
34910 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61  * Then as long a
34920 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  s the pattern st
34930 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65  ring remains the
34940 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f   same,.** the co
34950 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
34960 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
34970 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
34980 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
34990 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
349a0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
349b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
349c0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
349d0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
349e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
349f0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
34a00 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
34a10 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
34a20 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
34a30 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
34a40 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
34a50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34a60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
34a70 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
34a80 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
34a90 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75  ated with the fu
34aa0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c  nction argument,
34ab0 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65   this sqlite3_ge
34ac0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
34ad0 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
34ae0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
34af0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34b00 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34b10 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61  C,N,P,X) interfa
34b20 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65  ce saves P as me
34b30 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
34b40 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
34b50 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34b60 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34b70 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e  ion.  ^Subsequen
34b80 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
34b90 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
34ba0 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20  a(C,N) return P 
34bb0 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65  from the most re
34bc0 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cent.** sqlite3_
34bd0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
34be0 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65  P,X) call if the
34bf0 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69   metadata is sti
34c00 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e  ll valid or.** N
34c10 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64  ULL if the metad
34c20 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73  ata has been dis
34c30 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65  carded..** ^Afte
34c40 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73  r each call to s
34c50 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34c60 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72  ta(C,N,P,X) wher
34c70 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  e X is not NULL,
34c80 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
34c90 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
34ca0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58  uctor function X
34cb0 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20   with parameter 
34cc0 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63  P exactly.** onc
34cd0 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61  e, when the meta
34ce0 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65  data is discarde
34cf0 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  d..** SQLite is 
34d00 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20  free to discard 
34d10 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20  the metadata at 
34d20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64  any time, includ
34d30 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ing: <ul>.** <li
34d40 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  > when the corre
34d50 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
34d60 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
34d70 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ges, or.** <li> 
34d80 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  when [sqlite3_re
34d90 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
34da0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
34db0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  s called for the
34dc0 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61  .**      SQL sta
34dd0 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c  tement, or.** <l
34de0 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f  i> when sqlite3_
34df0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
34e00 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
34e10 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d  n the same param
34e20 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  eter, or.** <li>
34e30 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67   during the orig
34e40 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
34e50 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
34e60 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
34e70 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
34e80 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
34e90 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  </ul>)^.**.** No
34ea0 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
34eb0 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
34ec0 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
34ed0 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
34ee0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
34ef0 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
34f00 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
34f10 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a  ely, before the.
34f20 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
34f30 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
34f40 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e  ce even returns.
34f50 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f    Hence sqlite3_
34f60 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  set_auxdata().**
34f70 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
34f80 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f  d near the end o
34f90 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
34fa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  mplementation an
34fb0 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  d the.** functio
34fc0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
34fd0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65   should not make
34fe0 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66   any use of P af
34ff0 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ter.** sqlite3_s
35000 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73  et_auxdata() has
35010 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
35020 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
35030 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
35040 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
35050 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
35060 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  for.** function 
35070 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
35080 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  are compile-time
35090 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c   constants, incl
350a0 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a  uding literal.**
350b0 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
350c0 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70  ameters] and exp
350d0 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65  ressions compose
350e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e  d from the same.
350f0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
35100 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
35110 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
35120 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
35130 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
35140 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
35150 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
35160 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
35170 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
35180 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
35190 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
351a0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
351b0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
351c0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
351d0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
351e0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
351f0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
35200 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
35210 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
35220 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
35230 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
35240 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
35250 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
35260 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
35270 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
35280 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
35290 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
352a0 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
352b0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
352c0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
352d0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
352e0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
352f0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
35300 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
35310 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
35320 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
35330 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
35340 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
35350 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
35360 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
35370 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
35380 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
35390 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
353a0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
353b0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
353c0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
353d0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
353e0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
353f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
35400 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
35410 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
35420 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
35430 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
35440 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ers..*/.typedef 
35450 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
35460 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
35470 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
35480 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
35490 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
354a0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
354b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
354c0 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
354d0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
354e0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
354f0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
35500 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
35510 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
35520 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
35530 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
35540 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
35550 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
35560 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
35570 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
35580 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
35590 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
355a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
355b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
355c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
355d0 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
355e0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
355f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
35600 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
35610 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
35620 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
35630 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
35640 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
35650 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
35660 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
35670 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
35680 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
35690 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
356a0 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
356b0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
356c0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
356d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
356e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
356f0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
35700 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
35710 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
35720 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35730 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
35740 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
35750 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
35760 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
35770 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
35780 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
35790 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
357a0 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
357b0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
357c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
357d0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
357e0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
357f0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
35800 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35810 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35820 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
35830 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
35840 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
35850 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
35860 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
35870 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
35880 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
35890 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
358a0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
358b0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
358c0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
358d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
358e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
358f0 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
35900 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
35910 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
35920 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
35930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35940 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35950 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
35960 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
35970 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
35980 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
35990 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
359a0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
359b0 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
359c0 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
359d0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
359e0 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
359f0 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
35a00 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
35a10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35a20 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
35a30 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
35a40 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
35a50 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
35a60 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
35a70 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
35a80 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
35a90 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
35aa0 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
35ab0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
35ac0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
35ad0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
35ae0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
35af0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
35b00 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
35b10 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
35b20 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
35b30 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
35b40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35b50 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
35b60 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
35b70 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
35b80 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
35b90 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
35ba0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
35bb0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
35bc0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
35bd0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
35be0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35bf0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
35c00 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35c10 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
35c20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
35c30 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
35c40 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
35c50 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
35c60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
35c70 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
35c80 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
35c90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35ca0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
35cb0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
35cc0 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
35cd0 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
35ce0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
35cf0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
35d00 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
35d10 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
35d20 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
35d30 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
35d40 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
35d50 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
35d60 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
35d70 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
35d80 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
35d90 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
35da0 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
35db0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
35dc0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
35dd0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
35de0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
35df0 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
35e00 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
35e10 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
35e20 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
35e30 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
35e40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35e50 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
35e60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35e70 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
35e80 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
35e90 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
35ea0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35eb0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29  t_error_toobig()
35ec0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
35ed0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
35ee0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
35ef0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
35f00 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
35f10 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
35f20 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
35f30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35f40 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29  lt_error_nomem()
35f50 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
35f60 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
35f70 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
35f80 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
35f90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
35fa0 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
35fb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35fc0 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
35fd0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
35fe0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
35ff0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36000 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36010 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
36020 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
36030 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
36040 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
36050 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
36060 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
36070 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
36080 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
36090 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
360a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
360b0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
360c0 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
360d0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
360e0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
360f0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
36100 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36110 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
36120 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36130 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
36140 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
36150 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36160 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
36170 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
36180 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36190 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
361a0 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
361b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
361c0 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
361d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
361e0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
361f0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
36200 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
36210 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36220 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36230 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
36240 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
36250 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
36260 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
36270 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
36280 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
36290 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
362a0 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
362b0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
362c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
362d0 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e  sult_text64() in
362e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
362f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
36300 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69   an.** applicati
36310 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36320 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74  ion to be a text
36330 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e   string in an en
36340 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66  coding.** specif
36350 69 65 64 20 62 79 20 74 68 65 20 66 69 66 74 68  ied by the fifth
36360 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61   (and last) para
36370 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73  meter, which mus
36380 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b  t be one.** of [
36390 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
363a0 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53  QLITE_UTF16], [S
363b0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
363c0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
363d0 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  LE]..** ^SQLite 
363e0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
363f0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
36400 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
36410 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
36420 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
36430 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
36440 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
36450 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
36460 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
36470 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36480 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
36490 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
364a0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
364b0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
364c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
364d0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
364e0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
364f0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
36500 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
36510 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
36520 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36530 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
36540 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
36550 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
36560 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
36570 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
36580 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
36590 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
365a0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
365b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
365c0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
365d0 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33  esult.  If the 3
365e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
365f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
36600 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65  en it.** must be
36610 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
36620 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67   into the string
36630 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
36640 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a  erminator would.
36650 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65  ** appear if the
36660 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55   string where NU
36670 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  L terminated.  I
36680 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
36690 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ters occur.** in
366a0 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61   the string at a
366b0 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61   byte offset tha
366c0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74  t is less than t
366d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
366e0 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  3rd.** parameter
366f0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
36700 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c  ting string will
36710 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
36720 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a  d NULs and the.*
36730 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  * result of expr
36740 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e  essions operatin
36750 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74  g on strings wit
36760 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
36770 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
36780 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
36790 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
367a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
367b0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
367c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
367d0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
367e0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
367f0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
36800 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
36810 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
36820 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
36830 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
36840 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
36850 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
36860 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
36870 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
36880 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
36890 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
368a0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
368b0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
368c0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
368d0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
368e0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
368f0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
36900 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
36910 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
36920 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
36930 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
36940 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
36950 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
36960 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
36970 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
36980 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
36990 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
369a0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
369b0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
369c0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
369d0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
369e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
369f0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
36a00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36a10 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
36a20 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
36a30 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
36a40 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
36a50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
36a60 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
36a70 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
36a80 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
36a90 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
36aa0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
36ab0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36ac0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
36ad0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36ae0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
36af0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36b00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36b10 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
36b20 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
36b30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36b40 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
36b50 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
36b60 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
36b70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
36b80 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
36b90 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
36ba0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
36bb0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
36bc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
36bd0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
36be0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
36bf0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
36c00 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
36c10 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
36c20 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
36c30 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
36c40 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
36c50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
36c60 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
36c70 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
36c80 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
36c90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36ca0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
36cb0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
36cc0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
36cd0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36ce0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
36cf0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
36d00 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
36d10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
36d20 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
36d30 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
36d40 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
36d50 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
36d60 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
36d70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36d80 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
36d90 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
36da0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
36db0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
36dc0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
36dd0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
36de0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
36df0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36e00 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
36e10 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36e20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36e30 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69  sult_blob64(sqli
36e40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e  te3_context*,con
36e50 73 74 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20  st void*,.      
36e60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36e70 20 20 20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e       sqlite3_uin
36e80 74 36 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  t64,void(*)(void
36e90 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
36ea0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
36eb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36ec0 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
36ed0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36ee0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
36ef0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
36f00 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
36f10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36f20 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
36f30 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36f40 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
36f50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36f60 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
36f70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
36f80 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36f90 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
36fa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
36fb0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36fc0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
36fd0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36fe0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
36ff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
37000 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37010 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
37020 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
37030 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
37040 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
37050 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
37060 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
37070 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
37080 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37090 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
370a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
370b0 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
370c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
370d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
370e0 6c 74 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  lt_text64(sqlite
370f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37100 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
37110 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
37120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37130 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
37140 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
37150 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64   encoding);.void
37160 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37170 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
37180 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37190 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
371a0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
371b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
371c0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
371d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
371e0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
371f0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
37200 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37210 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
37220 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37230 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
37240 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
37250 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37260 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
37270 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
37280 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
37290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
372a0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
372b0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
372c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
372d0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
372e0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
372f0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
37300 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
37310 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
37320 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
37330 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
37340 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
37350 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
37360 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
37370 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
37380 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
37390 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
373a0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
373b0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
373c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
373d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
373e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
373f0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
37400 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
37410 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
37420 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
37430 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
37440 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
37450 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
37460 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
37470 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
37480 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
37490 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
374a0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
374b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
374c0 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
374d0 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
374e0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
374f0 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
37500 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
37510 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
37520 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
37530 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
37540 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
37550 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
37560 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
37570 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
37580 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
37590 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
375a0 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
375b0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
375c0 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
375d0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
375e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
375f0 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
37600 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
37610 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
37620 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
37630 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
37640 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
37650 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
37660 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
37670 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
37680 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
37690 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
376a0 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
376b0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
376c0 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
376d0 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
376e0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
376f0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
37700 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
37710 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
37720 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
37730 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
37740 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
37750 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
37760 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37770 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
37780 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
37790 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20  ent, xCallback, 
377a0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
377b0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
377c0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74  nction..** ^Mult
377d0 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  iple collating f
377e0 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20  unctions can be 
377f0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
37800 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
37810 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65  ut.** with diffe
37820 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61  rent eTextRep pa
37830 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c  rameters and SQL
37840 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69  ite will use whi
37850 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69  chever.** functi
37860 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20  on requires the 
37870 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
37880 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74  data transformat
37890 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
378a0 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65  xCallback argume
378b0 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  nt is NULL then 
378c0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
378d0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c  nction is.** del
378e0 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c  eted.  ^When all
378f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37900 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20  ions having the 
37910 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65  same name are de
37920 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63  leted,.** that c
37930 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  ollation is no l
37940 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a  onger usable..**
37950 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69  .** ^The collati
37960 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
37970 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
37980 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74  with a copy of t
37990 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c  he pArg .** appl
379a0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
379b0 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77  nter and with tw
379c0 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  o strings in the
379d0 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
379e0 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54  ied.** by the eT
379f0 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e  extRep argument.
37a00 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20    The collating 
37a10 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65  function must re
37a20 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  turn an.** integ
37a30 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74  er that is negat
37a40 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f  ive, zero, or po
37a50 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65  sitive.** if the
37a60 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
37a70 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
37a80 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
37a90 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
37aa0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
37ab0 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  y.  A collating 
37ac0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c  function must al
37ad0 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
37ae0 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67  same answer.** g
37af0 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e  iven the same in
37b00 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72  puts.  If two or
37b10 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20   more collating 
37b20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65  functions are re
37b30 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74  gistered.** to t
37b40 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f  he same collatio
37b50 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69  n name (using di
37b60 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
37b70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c   values) then al
37b80 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61  l.** must give a
37b90 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73  n equivalent ans
37ba0 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64  wer when invoked
37bb0 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74   with equivalent
37bc0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
37bd0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37be0 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68  ion must obey th
37bf0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70  e following prop
37c00 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a  erties for all.*
37c10 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20  * strings A, B, 
37c20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  and C:.**.** <ol
37c30 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  >.** <li> If A==
37c40 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20  B then B==A..** 
37c50 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64  <li> If A==B and
37c60 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e   B==C then A==C.
37c70 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
37c80 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a  ;B THEN B&gt;A..
37c90 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
37ca0 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65  B and B&lt;C the
37cb0 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f  n A&lt;C..** </o
37cc0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f  l>.**.** If a co
37cd0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37ce0 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68   fails any of th
37cf0 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69  e above constrai
37d00 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20  nts and that.** 
37d10 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37d20 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65  on is  registere
37d30 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e  d and used, then
37d40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
37d50 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e   SQLite.** is un
37d60 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
37d70 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
37d80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37d90 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
37da0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37db0 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20  ation().** with 
37dc0 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61  the addition tha
37dd0 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63  t the xDestroy c
37de0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
37df0 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a  ed on pArg when.
37e00 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** the collating
37e10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
37e20 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  eted..** ^Collat
37e30 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
37e40 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  e deleted when t
37e50 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
37e60 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63  en by later.** c
37e70 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
37e80 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
37e90 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
37ea0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
37eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
37ec0 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
37ed0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
37ee0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73  .**.** ^The xDes
37ef0 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
37f00 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c   <u>not</u> call
37f10 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71  ed if the .** sq
37f20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37f30 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63  lation_v2() func
37f40 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70  tion fails.  App
37f50 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69  lications that i
37f60 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
37f70 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37f80 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f  n_v2() with a no
37f90 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
37fa0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
37fb0 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65  .** check the re
37fc0 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69  turn code and di
37fd0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70  spose of the app
37fe0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
37ff0 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c  inter.** themsel
38000 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20  ves rather than 
38010 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65  expecting SQLite
38020 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74   to deal with it
38030 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68   for them..** Th
38040 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20  is is different 
38050 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72  from every other
38060 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
38070 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73  e.  The inconsis
38080 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66  tency .** is unf
38090 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e  ortunate but can
380a0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77  not be changed w
380b0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
380c0 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f  backwards .** co
380d0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
380e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
380f0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
38100 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
38110 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
38120 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
38130 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
38140 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
38150 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
38160 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
38170 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
38180 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
38190 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
381a0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
381b0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
381c0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
381d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
381e0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
381f0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
38200 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
38210 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
38220 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
38230 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
38240 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
38250 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
38260 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
38270 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
38280 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
38290 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
382a0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
382b0 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
382c0 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
382d0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
382e0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
382f0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
38300 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
38310 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
38320 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38330 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
38340 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
38350 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
38360 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
38370 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
38380 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
38390 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
383a0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
383b0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
383c0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
383d0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
383e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
383f0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69  nection] to be i
38400 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
38410 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
38420 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
38430 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
38440 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75  **.** ^If the fu
38450 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
38460 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
38470 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
38480 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
38490 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
384a0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
384b0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
384c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
384d0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
384e0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e  oded in UTF-8. ^
384f0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
38500 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
38510 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
38520 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
38530 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
38540 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
38550 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63  e order..** ^A c
38560 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
38570 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
38580 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c  the existing col
38590 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61  lation-needed ca
385a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28  llback..**.** ^(
385b0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
385c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
385d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
385e0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
385f0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
38600 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
38610 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
38620 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
38630 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
38640 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
38650 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
38660 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
38670 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
38680 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
38690 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
386a0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
386b0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
386c0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
386d0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
386e0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
386f0 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
38700 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
38710 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
38720 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
38730 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
38740 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
38750 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
38760 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
38770 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  nce.)^.**.** The
38780 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38790 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
387a0 65 72 20 74 68 65 20 64 65 73 69 72