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

Artifact 64287a2b3432550264a743addbf4162a692fdd1c:


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 0a 2f 2a 20  VFS only */../* 
62d0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
62e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
62f0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
6300: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6310: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6320: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
6330: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6340: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6350: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6360: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
6370: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
6380: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
6390: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
63a0: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
63b0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
63c0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
63d0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
63e0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
63f0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
6400: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
6410: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6420: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
6430: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6440: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6450: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6460: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
6470: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
6480: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6490: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
64a0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
64b0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
64c0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
64d0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
64e0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
64f0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
6500: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6510: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6520: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6530: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6540: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6550: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6560: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
6570: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
6580: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6590: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
65a0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
65b0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
65c0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
65d0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
65e0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
65f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6600: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6610: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6620: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6630: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6640: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6650: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6660: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
6670: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6680: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6690: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
66a0: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
66b0: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
66c0: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
66d0: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
66e0: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
66f0: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
6700: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
6710: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6720: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
6730: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
6740: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6750: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
6760: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
6770: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
6780: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
6790: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
67a0: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
67b0: 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61  WHEN_OPEN.** fla
67c0: 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  g indicate that 
67d0: 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  a file cannot be
67e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70   deleted when op
67f0: 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49  en.  The.** SQLI
6800: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
6810: 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  LE flag indicate
6820: 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20  s that the file 
6830: 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e  is on.** read-on
6840: 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e  ly media and can
6850: 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65  not be changed e
6860: 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73  ven by processes
6870: 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65   with.** elevate
6880: 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f  d privileges..*/
6890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
68a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
68b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
68c0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
68d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68e0: 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20  MIC512          
68f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
6900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6910: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
6920: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6930: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
6940: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6950: 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C2K             
6960: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
6970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6980: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
6990: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
69a0: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
69b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
69c0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
69d0: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
69e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
69f0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
6a00: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6a10: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6a20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a40: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
6a50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a60: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20  OMIC64K         
6a70: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
6a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6a90: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6aa0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ab0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
6ac0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6ad0: 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20  ENTIAL          
6ae0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
6af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b00: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
6b10: 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30  HEN_OPEN  0x0000
6b20: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
6b30: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
6b40: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
6b50: 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66   0x00001000.#def
6b60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b70: 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20  _IMMUTABLE      
6b80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30          0x000020
6b90: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
6ba0: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
6bb0: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
6bc0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
6bd0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
6be0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
6bf0: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
6c00: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
6c10: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
6c20: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
6c30: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
6c40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6c50: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
6c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6c70: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
6c80: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
6c90: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
6ca0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
6cb0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6cc0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
6cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6ce0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
6cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6d00: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
6d10: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
6d20: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
6d30: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
6d40: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
6d50: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
6d60: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
6d70: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
6d80: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6d90: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
6da0: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
6db0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6dc0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6dd0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
6de0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
6df0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
6e00: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
6e10: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
6e20: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
6e30: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
6e40: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
6e50: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
6e60: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
6e70: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
6e80: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77  shed. If the low
6e90: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20  er four bits of 
6ea0: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61  the flag.** equa
6eb0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  l SQLITE_SYNC_NO
6ec0: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  RMAL, that means
6ed0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
6ee0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
6ef0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65  ..** If the lowe
6f00: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61  r four bits equa
6f10: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  l SQLITE_SYNC_FU
6f20: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  LL, that means.*
6f30: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20  * to use Mac OS 
6f40: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6f50: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
6f60: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f  c()..**.** Do no
6f70: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51  t confuse the SQ
6f80: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6f90: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6fa0: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77  _FULL flags.** w
6fb0: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ith the [PRAGMA 
6fc0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52  synchronous]=NOR
6fd0: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  MAL and [PRAGMA 
6fe0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c  synchronous]=FUL
6ff0: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20  L.** settings.  
7000: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73  The [synchronous
7010: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69   pragma] determi
7020: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74  nes when calls t
7030: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56  o the.** xSync V
7040: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20  FS method occur 
7050: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66  and applies unif
7060: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  ormly across all
7070: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54   platforms..** T
7080: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
7090: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
70a0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
70b0: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a   determine how.*
70c0: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72  * energetic or r
70d0: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65  igorous or force
70e0: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65  ful the sync ope
70f0: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a  rations are and.
7100: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64  ** only make a d
7110: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63  ifference on Mac
7120: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66   OSX for the def
7130: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65  ault SQLite code
7140: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74  ..** (Third-part
7150: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  y VFS implementa
7160: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f  tions might also
7170: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
7180: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
7190: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
71a0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
71b0: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d  YNC_FULL, but am
71c0: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61  ong the.** opera
71d0: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74  ting systems nat
71e0: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20  ively supported 
71f0: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20  by SQLite, only 
7200: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73  Mac OSX.** cares
7210: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65   about the diffe
7220: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69  rence.).*/.#defi
7230: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
7240: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
7250: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
7260: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
7270: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
7280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7290: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
72a0: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
72b0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
72c0: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
72d0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e   Handle.**.** An
72e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
72f0: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
7300: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
7310: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
7320: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
7330: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
7340: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
7350: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
7360: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
7370: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
7380: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
7390: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
73a0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
73b0: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
73c0: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
73d0: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
73e0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
73f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7400: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
7410: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
7420: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
7430: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
7440: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
7450: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7460: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
7470: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
7480: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7490: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
74a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
74b0: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
74c0: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
74d0: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
74e0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
74f0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7500: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
7510: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
7520: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
7530: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
7540: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7550: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  ] method populat
7560: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
7570: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
7580: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
7590: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
75a0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
75b0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
75c0: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
75d0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
75e0: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
75f0: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
7600: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
7610: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
7620: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
7630: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
7640: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
7650: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
7660: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7670: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ject..**.** If t
7680: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7690: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65  xOpen] method se
76a0: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
76b0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
76c0: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
76d0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
76e0: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
76f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
7700: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
7710: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
7720: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
7730: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f  _vfs.xOpen] repo
7740: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69  rted that it fai
7750: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c  led.  The.** onl
7760: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74  y way to prevent
7770: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73   a call to xClos
7780: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  e following a fa
7790: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66  iled [sqlite3_vf
77a0: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66  s.xOpen].** is f
77b0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
77c0: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65  vfs.xOpen] to se
77d0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
77e0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
77f0: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a  ent.** to NULL..
7800: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
7810: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
7820: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
7830: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
7840: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
7850: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
7860: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
7870: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
7880: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
7890: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
78a0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
78b0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
78c0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
78d0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
78e0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
78f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
7900: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
7910: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
7920: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
7930: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
7940: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
7950: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
7960: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7970: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
7980: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7990: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
79a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
79b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
79c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
79d0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
79e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
79f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
7a00: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
7a10: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7a20: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
7a30: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
7a40: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
7a50: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
7a60: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
7a70: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
7a80: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
7a90: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
7aa0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7ab0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
7ac0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
7ad0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
7ae0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
7af0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
7b00: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
7b10: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
7b20: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
7b30: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
7b40: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
7b50: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
7b60: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
7b70: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
7b80: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
7b90: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
7ba0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
7bb0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
7bc0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
7bd0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
7be0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
7bf0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
7c00: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
7c20: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
7c30: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
7c40: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
7c50: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
7c60: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
7c70: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
7c80: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
7c90: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
7ca0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
7cb0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
7cc0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
7cd0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
7ce0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
7cf0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
7d00: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
7d10: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
7d20: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
7d30: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
7d40: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
7d50: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
7d60: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
7d70: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
7d80: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
7d90: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
7da0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
7db0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
7dc0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
7dd0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
7de0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
7df0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
7e00: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
7e10: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69  wn use..** A [fi
7e20: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e30: 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  es | list of opc
7e40: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
7e50: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
7e60: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
7e70: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
7e80: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
7e90: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
7ea0: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
7eb0: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
7ec0: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
7ed0: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65  icts.  VFS imple
7ee0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
7ef0: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
7f00: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f  ITE_NOTFOUND] fo
7f10: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  r file control o
7f20: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79  pcodes that they
7f30: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67   do not.** recog
7f40: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nize..**.** The 
7f50: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
7f60: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
7f70: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
7f80: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
7f90: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
7fa0: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
7fb0: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
7fc0: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
7fd0: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
7fe0: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
7ff0: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
8000: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
8010: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
8020: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8030: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
8040: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
8050: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
8060: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
8070: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
8080: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
8090: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
80a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
80b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
80c0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
80d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
80e0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
80f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8100: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
8110: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8120: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
8130: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8140: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
8150: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8160: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
8170: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8180: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
8190: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
81a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
81b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
81c0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
81d0: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
81e0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
81f0: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
8200: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
8210: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
8220: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8230: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8240: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
8250: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8260: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8270: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8280: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8290: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
82a0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
82b0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
82c0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
82d0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
82e0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
82f0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8300: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8310: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8320: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8330: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8340: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
8350: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
8360: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8370: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8380: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8390: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
83a0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
83b0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
83c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
83d0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
83e0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
83f0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8400: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8410: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8420: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8430: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8440: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
8450: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
8460: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8470: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8480: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8490: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
84a0: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
84b0: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
84c0: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
84d0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
84e0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
84f0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8500: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8510: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8520: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8530: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8540: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
8550: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
8560: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8570: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8580: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8590: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
85a0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
85b0: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
85c0: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
85d0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
85e0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
85f0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8600: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8610: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8620: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8630: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8640: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
8650: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8660: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8670: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8680: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8690: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
86a0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
86b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
86c0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
86d0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
86e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
86f0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8700: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8710: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8720: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8730: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8740: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8750: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
8760: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8770: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8780: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8790: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
87a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
87b0: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
87c0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
87d0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
87e0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
87f0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8800: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8810: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8820: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8830: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8840: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8850: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8860: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8870: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8880: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8890: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
88a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
88b0: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
88c0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
88d0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
88e0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
88f0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8900: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8910: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8920: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8930: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8940: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8950: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
8960: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8970: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8980: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
8990: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
89a0: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
89b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
89c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
89d0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
89e0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
89f0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8a00: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8a10: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8a20: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8a30: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8a40: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
8a50: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8a60: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8a70: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
8a80: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
8a90: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
8aa0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8ab0: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
8ac0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8ad0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8ae0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8af0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8b00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8b10: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8b20: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8b30: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8b40: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8b50: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
8b60: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8b70: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
8b80: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8b90: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8ba0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8bb0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8bc0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8bd0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8be0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8bf0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8c00: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8c10: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8c30: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8c40: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8c50: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8c60: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8c70: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8c80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8c90: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8ca0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8cb0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8cc0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8cd0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8ce0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8cf0: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
8d00: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
8d10: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
8d20: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
8d30: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
8d40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8d50: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8d60: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
8d70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8d80: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
8d90: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
8da0: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
8db0: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
8dc0: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
8dd0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
8de0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
8df0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
8e00: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
8e10: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
8e20: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
8e30: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
8e40: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
8e50: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
8e60: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
8e70: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
8e80: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
8e90: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
8ea0: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
8eb0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
8ec0: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
8ed0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8ee0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
8ef0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8f00: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8f10: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8f20: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8f30: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
8f40: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
8f50: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
8f60: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
8f70: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
8f80: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
8f90: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
8fa0: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
8fb0: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
8fc0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
8fd0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8fe0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
8ff0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
9000: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
9010: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
9020: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
9030: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
9040: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9050: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9060: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9070: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9080: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9090: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
90a0: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
90b0: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
90c0: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
90d0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
90e0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
90f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9100: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9110: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9120: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9130: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
9140: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9150: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9160: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9170: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9180: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9190: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
91a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
91b0: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  e the [sqlite3_f
91c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64  ile_control()] d
91d0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
91e0: 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
91f0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
9200: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9210: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
9220: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
9230: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
9240: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9250: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
9260: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9270: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9280: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9290: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
92a0: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
92b0: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
92c0: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
92d0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
92e0: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
92f0: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
9300: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
9310: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
9320: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
9330: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
9340: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
9350: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
9360: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
9370: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9380: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9390: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
93a0: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
93b0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
93c0: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
93d0: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
93e0: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
93f0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
9400: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
9410: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
9420: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
9430: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
9440: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
9450: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
9460: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
9470: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9480: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9490: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
94a0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
94b0: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
94c0: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
94d0: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
94e0: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
94f0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9500: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9510: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
9520: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
9530: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
9540: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9550: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9560: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
9570: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9580: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9590: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
95a0: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
95b0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
95c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
95d0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
95e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
95f0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9600: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
9610: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
9620: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
9630: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
9640: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
9650: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
9660: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
9670: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9680: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9690: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
96a0: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
96b0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
96c0: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
96d0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
96e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
96f0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
9700: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
9710: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9720: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
9730: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9740: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9750: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9760: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9770: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9780: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9790: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
97a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
97b0: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
97c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
97d0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
97e0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
97f0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9800: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9810: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9820: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9830: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9840: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9850: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9860: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9870: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9880: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9890: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
98a0: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
98b0: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
98c0: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
98d0: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
98e0: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
98f0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9900: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9910: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9920: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9930: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9940: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9950: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9960: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9970: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9980: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9990: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
99a0: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
99b0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
99c0: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
99d0: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
99e0: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
99f0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9a00: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9a10: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9a20: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9a30: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9a40: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9a50: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9a60: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9a70: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9a80: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9a90: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9aa0: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9ab0: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
9ac0: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9ad0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9ae0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9af0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9b00: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9b10: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9b20: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9b30: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9b40: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9b50: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9b60: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9b70: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9b80: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9b90: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
9ba0: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
9bb0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
9bc0: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
9bd0: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
9be0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9bf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9c00: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
9c10: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9c20: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
9c30: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9c40: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9c50: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
9c60: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
9c70: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
9c80: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9c90: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
9ca0: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
9cb0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9cc0: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
9cd0: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
9ce0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
9cf0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
9d00: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
9d10: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
9d20: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
9d30: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
9d40: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9d50: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
9d60: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
9d70: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
9d80: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
9d90: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
9da0: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
9db0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
9dc0: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
9dd0: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
9de0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
9df0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
9e00: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
9e10: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
9e20: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
9e30: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
9e40: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
9e50: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
9e60: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
9e70: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
9e80: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
9e90: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9ea0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9eb0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9ec0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9ed0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9ee0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9ef0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
9f00: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
9f10: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9f20: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9f30: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
9f40: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
9f50: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
9f60: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
9f70: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
9f80: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
9f90: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
9fa0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
9fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9fc0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9fd0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
9fe0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9ff0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a000: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a010: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a020: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a030: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a040: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a050: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a060: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a070: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a080: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a090: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a0a0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a0b0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a0c0: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a0d0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a0e0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a0f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a100: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a110: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a120: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a130: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a140: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a150: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a160: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a170: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a180: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a190: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a1a0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a1b0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a1c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
a1d0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
a1e0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a1f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
a200: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a210: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a220: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a230: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
a240: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
a250: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
a260: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
a270: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
a280: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
a290: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
a2a0: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
a2b0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
a2c0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
a2d0: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
a2e0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
a2f0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
a300: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
a310: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
a320: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a330: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
a340: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a350: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
a360: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
a370: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
a380: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
a390: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
a3a0: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
a3b0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
a3c0: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
a3d0: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
a3e0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
a3f0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
a400: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a410: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a420: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
a430: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
a440: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
a450: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
a460: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a470: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
a480: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a490: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
a4a0: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
a4b0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
a4c0: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
a4d0: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
a4e0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
a4f0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
a500: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
a510: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
a520: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
a530: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
a540: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
a550: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
a560: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
a570: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
a580: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
a590: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
a5a0: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
a5b0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
a5c0: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
a5d0: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
a5e0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
a5f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a600: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
a610: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
a620: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
a630: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
a640: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a650: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
a660: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
a670: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
a680: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
a690: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
a6a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a6b0: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
a6c0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a6d0: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
a6e0: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
a6f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a700: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a710: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
a720: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
a730: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
a740: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
a750: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
a760: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
a770: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
a780: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
a790: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
a7a0: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
a7b0: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
a7c0: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
a7d0: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
a7e0: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
a7f0: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
a800: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a810: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a820: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
a830: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
a840: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
a850: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
a860: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
a870: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
a880: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
a890: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
a8a0: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
a8b0: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
a8c0: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
a8d0: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
a8e0: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
a8f0: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
a900: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
a910: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
a920: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a930: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a940: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
a950: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
a960: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
a970: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
a980: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
a990: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a9a0: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
a9b0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
a9c0: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
a9d0: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
a9e0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
a9f0: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
aa00: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
aa10: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
aa20: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
aa30: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
aa40: 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20  ement if result 
aa50: 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20  string is NULL, 
aa60: 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20  or that returns 
aa70: 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
aa80: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69   result string i
aa90: 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20  f the string is 
aaa0: 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66  non-NULL..** ^If
aab0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
aac0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
aad0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a  control returns.
aae0: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f  ** any result co
aaf0: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  de other than [S
ab00: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51  QLITE_OK] or [SQ
ab10: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
ab20: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  that means.** th
ab30: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75  at the VFS encou
ab40: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20  ntered an error 
ab50: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74  while handling t
ab60: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20  he [PRAGMA] and 
ab70: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69  the.** compilati
ab80: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41  on of the PRAGMA
ab90: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65   fails with an e
aba0: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c  rror.  ^The [SQL
abb0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
abc0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
abd0: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20  l occurs at the 
abe0: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61  beginning of pra
abf0: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  gma statement an
ac00: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a  alysis and so.**
ac10: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f   it is able to o
ac20: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e  verride built-in
ac30: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
ac40: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ents..**.** <li>
ac50: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
ac60: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20  USYHANDLER]].** 
ac70: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
ac80: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a  TL_BUSYHANDLER].
ac90: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
aca0: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62  may be invoked b
acb0: 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20  y SQLite on the 
acc0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61  database file ha
acd0: 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20  ndle.** shortly 
ace0: 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e  after it is open
acf0: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70  ed in order to p
ad00: 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20  rovide a custom 
ad10: 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a  VFS with access.
ad20: 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63  ** to the connec
ad30: 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c  tions busy-handl
ad40: 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65  er callback. The
ad50: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20   argument is of 
ad60: 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a  type (void **).*
ad70: 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20  * - an array of 
ad80: 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c  two (void *) val
ad90: 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28  ues. The first (
ada0: 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79  void *) actually
adb0: 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20   points.** to a 
adc0: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
add0: 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a   (int (*)(void *
ade0: 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  )). In order to 
adf0: 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65  invoke the conne
ae00: 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68  ctions.** busy-h
ae10: 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e  andler, this fun
ae20: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ction should be 
ae30: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65  invoked with the
ae40: 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29   second (void *)
ae50: 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79   in.** the array
ae60: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67   as the only arg
ae70: 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74  ument. If it ret
ae80: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
ae90: 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f  hen the operatio
aea0: 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
aeb0: 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65  etried. If it re
aec0: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
aed0: 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c  custom VFS shoul
aee0: 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a  d abandon the.**
aef0: 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
af00: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
af10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
af20: 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  PFILENAME]].** ^
af30: 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  Application can 
af40: 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49  invoke the [SQLI
af50: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
af60: 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74  ENAME] file-cont
af70: 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53  rol.** to have S
af80: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61  QLite generate a
af90: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
afa0: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65  lename using the
afb0: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
afc0: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64  that is followed
afd0: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20   to generate.** 
afe0: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
aff0: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62  mes for TEMP tab
b000: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e  les and other in
b010: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68  ternal uses.  Th
b020: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  e.** argument sh
b030: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a  ould be a char**
b040: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66   which will be f
b050: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  illed with the f
b060: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74  ilename.** writt
b070: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
b080: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b090: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
b0a0: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f    The caller sho
b0b0: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73  uld.** invoke [s
b0c0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
b0d0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20  n the result to 
b0e0: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
b0f0: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  eak..**.** <li>[
b100: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
b110: 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  AP_SIZE]].** The
b120: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
b130: 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
b140: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74  ontrol is used t
b150: 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74  o query or set t
b160: 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75  he.** maximum nu
b170: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68  mber of bytes th
b180: 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  at will be used 
b190: 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65  for memory-mappe
b1a0: 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72  d I/O..** The ar
b1b0: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
b1c0: 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f  ter to a value o
b1d0: 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69  f type sqlite3_i
b1e0: 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20  nt64 that.** is 
b1f0: 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69  an advisory maxi
b200: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b210: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20  tes in the file 
b220: 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20  to memory map.  
b230: 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  The.** pointer i
b240: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
b250: 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65  th the old value
b260: 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  .  The limit is 
b270: 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a  not changed if.*
b280: 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67  * the value orig
b290: 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74  inally pointed t
b2a0: 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61  o is negative, a
b2b0: 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e  nd so the curren
b2c0: 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20  t limit .** can 
b2d0: 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61  be queried by pa
b2e0: 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74  ssing in a point
b2f0: 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65  er to a negative
b300: 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a   number.  This.*
b310: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  * file-control i
b320: 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
b330: 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  y to implement [
b340: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
b350: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
b360: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b370: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b380: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  TE_FCNTL_TRACE] 
b390: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f  file control pro
b3a0: 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69  vides advisory i
b3b0: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f  nformation.** to
b3c0: 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77   the VFS about w
b3d0: 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c  hat the higher l
b3e0: 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c  ayers of the SQL
b3f0: 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f  ite stack are do
b400: 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c  ing..** This fil
b410: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b420: 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63  d by some VFS ac
b430: 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b  tivity tracing [
b440: 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  shims]..** The a
b450: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72  rgument is a zer
b460: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
b470: 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79  ing.  Higher lay
b480: 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51  ers in the.** SQ
b490: 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67  Lite stack may g
b4a0: 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65  enerate instance
b4b0: 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63  s of this file c
b4c0: 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65  ontrol if.** the
b4d0: 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e   [SQLITE_USE_FCN
b4e0: 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  TL_TRACE] compil
b4f0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
b500: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
b510: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b520: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a  TL_HAS_MOVED]].*
b530: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b540: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66  NTL_HAS_MOVED] f
b550: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65  ile control inte
b560: 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d  rprets its argum
b570: 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e  ent as a.** poin
b580: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
b590: 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20  r and it writes 
b5a0: 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74  a boolean into t
b5b0: 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65  hat integer depe
b5c0: 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74  nding.** on whet
b5d0: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66  her or not the f
b5e0: 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e  ile has been ren
b5f0: 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20  amed, moved, or 
b600: 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74  deleted since it
b610: 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70  .** was first op
b620: 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ened..**.** <li>
b630: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
b640: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d  IN32_SET_HANDLE]
b650: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b660: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
b670: 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20  _HANDLE] opcode 
b680: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
b690: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
b6a0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
b6b0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
b6c0: 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68  ethod to swap th
b6d0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69  e file handle wi
b6e0: 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f  th the one.** po
b6f0: 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
b700: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20  pArg argument.  
b710: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20  This capability 
b720: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
b730: 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e  esting.** and on
b740: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
b750: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
b760: 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66  LITE_TEST is def
b770: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ined..**.** <li>
b780: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  [[SQLITE_FCNTL_W
b790: 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68  AL_BLOCK]].** Th
b7a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b7b0: 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20  WAL_BLOCK] is a 
b7c0: 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46  signal to the VF
b7d0: 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20  S layer that it 
b7e0: 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61  might.** be adva
b7f0: 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63  ntageous to bloc
b800: 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41  k on the next WA
b810: 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f  L lock if the lo
b820: 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69  ck is not immedi
b830: 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62  ately.** availab
b840: 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62  le.  The WAL sub
b850: 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68  system issues th
b860: 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67  is signal during
b870: 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73   rare.** circums
b880: 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20  tances in order 
b890: 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d  to fix a problem
b8a0: 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69   with priority i
b8b0: 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70  nversion..** App
b8c0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
b8d0: 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73   <em>not</em> us
b8e0: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
b8f0: 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e  rol..**.** </ul>
b900: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
b910: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
b920: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
b930: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
b940: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
b950: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
b960: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
b970: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
b980: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33  ROXYFILE       3
b990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9a0: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
b9b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
b9c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9d0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
b9e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
b9f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ba00: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
ba10: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
ba20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ba30: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
ba40: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
ba50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba60: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
ba70: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
ba80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ba90: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
baa0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
bab0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bac0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
bad0: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
bae0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
baf0: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
bb00: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
bb10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
bb20: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
bb30: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
bb40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
bb50: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
bb60: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
bb70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
bb80: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
bb90: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
bba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
bbb0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
bbc0: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
bbd0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
bbe0: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
bbf0: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
bc00: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
bc10: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
bc20: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
bc40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
bc50: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
bc60: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
bc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
bc80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bc90: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
bca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
bcb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bcc0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
bcd0: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
bce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bcf0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
bd00: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64  NDLE       23.#d
bd10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bd20: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20  TL_WAL_BLOCK    
bd30: 20 20 20 20 20 20 20 20 20 20 32 34 0a 0a 2f 2a            24../*
bd40: 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65   deprecated name
bd50: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
bd60: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
bd70: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
bd80: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
bd90: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
bda0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
bdb0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
bdc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
bdd0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
bde0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
bdf0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
be00: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
be10: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f  L_LAST_ERRNO.../
be20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
be30: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
be40: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
be50: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
be60: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
be70: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
be80: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
be90: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
bea0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
beb0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
bec0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
bed0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
bee0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
bef0: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
bf00: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
bf10: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
bf20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
bf30: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
bf40: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
bf50: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
bf60: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
bf70: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
bf80: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
bf90: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
bfa0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
bfb0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
bfc0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
bfd0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
bfe0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
bff0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
c000: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
c010: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
c020: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
c030: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
c040: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
c050: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
c060: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
c070: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
c080: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
c090: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
c0a0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
c0b0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
c0c0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
c0d0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
c0e0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
c0f0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
c100: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
c110: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
c120: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
c130: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
c140: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
c150: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
c160: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
c170: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
c180: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
c190: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
c1a0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
c1b0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
c1c0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
c1d0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
c1e0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
c1f0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
c200: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
c210: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
c220: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
c230: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
c240: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
c250: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
c260: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
c270: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
c280: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
c290: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
c2a0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
c2b0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
c2c0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
c2d0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
c2e0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
c2f0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
c300: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
c310: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
c320: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
c330: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
c340: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
c350: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
c360: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
c370: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
c380: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
c390: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
c3a0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
c3b0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
c3c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
c3d0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
c3e0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
c3f0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
c400: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
c410: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
c420: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c430: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
c440: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
c450: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
c460: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
c470: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
c480: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
c490: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
c4a0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
c4b0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
c4c0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
c4d0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
c4e0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
c4f0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
c500: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
c510: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
c520: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
c530: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
c540: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
c550: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
c560: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
c570: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
c580: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
c590: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
c5a0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
c5b0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
c5c0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
c5d0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
c5e0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
c5f0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
c600: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
c610: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
c620: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
c630: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c640: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
c650: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
c660: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
c670: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
c680: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
c690: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
c6a0: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
c6b0: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
c6c0: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
c6d0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c6e0: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
c6f0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
c700: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
c710: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
c720: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
c730: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
c740: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
c750: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
c760: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
c770: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
c780: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
c790: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
c7a0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
c7b0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
c7c0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
c7d0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
c7e0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
c7f0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
c800: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
c810: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
c820: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
c830: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
c840: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
c850: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
c860: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
c870: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
c880: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
c890: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
c8a0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
c8b0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
c8c0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
c8d0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
c8e0: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
c8f0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
c900: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
c910: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
c920: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
c930: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
c940: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c950: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
c960: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
c970: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
c980: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
c990: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
c9a0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
c9b0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
c9c0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
c9d0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
c9e0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
c9f0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
ca00: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
ca10: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
ca20: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
ca30: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
ca40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
ca50: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
ca60: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
ca70: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
ca80: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
ca90: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
caa0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
cab0: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
cac0: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
cad0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
cae0: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
caf0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
cb00: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
cb10: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
cb20: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
cb30: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
cb40: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
cb50: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
cb60: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cb70: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
cb80: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cb90: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
cba0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
cbb0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
cbc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cbd0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
cbe0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cbf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
cc00: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
cc10: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
cc20: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
cc30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cc40: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
cc50: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cc60: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
cc70: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
cc80: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
cc90: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
cca0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
ccb0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
ccc0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
ccd0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
cce0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
ccf0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
cd00: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
cd10: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
cd20: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
cd30: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
cd40: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
cd50: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
cd60: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
cd70: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
cd80: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
cd90: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
cda0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
cdb0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
cdc0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
cdd0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
cde0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
cdf0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
ce00: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
ce10: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
ce20: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
ce30: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
ce40: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
ce50: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
ce60: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
ce70: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
ce80: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
ce90: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
cea0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
ceb0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
cec0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
ced0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
cee0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
cef0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
cf00: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
cf10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
cf20: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
cf30: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
cf40: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cf50: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
cf60: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
cf70: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
cf80: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
cf90: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
cfa0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
cfb0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
cfc0: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
cfd0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
cfe0: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
cff0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
d000: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
d010: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
d020: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
d030: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
d040: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
d050: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
d060: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
d070: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
d080: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
d090: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
d0a0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
d0b0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
d0c0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
d0d0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
d0e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
d0f0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
d100: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
d110: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
d120: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
d130: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
d140: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
d150: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
d160: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
d170: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
d180: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
d190: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
d1a0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
d1b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
d1c0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
d1d0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
d1e0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
d1f0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
d200: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
d210: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
d220: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
d230: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
d240: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
d250: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
d260: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
d270: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
d280: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
d290: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
d2a0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
d2b0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
d2c0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
d2d0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
d2e0: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
d2f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
d300: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
d310: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
d320: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
d330: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
d340: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
d350: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
d360: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
d370: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
d380: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
d390: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
d3a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
d3b0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
d3c0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
d3d0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
d3e0: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
d3f0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
d400: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
d410: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
d420: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
d430: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
d440: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
d450: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
d460: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
d470: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d480: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
d490: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
d4a0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
d4b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d4c0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
d4d0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d4e0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
d4f0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
d500: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d510: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
d520: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d530: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
d540: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
d550: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
d560: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
d570: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
d580: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
d590: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
d5a0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
d5b0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
d5c0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
d5d0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
d5e0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
d5f0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
d600: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
d610: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
d620: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
d630: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
d640: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
d650: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
d660: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
d670: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
d680: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
d690: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
d6a0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
d6b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
d6c0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
d6d0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
d6e0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
d6f0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
d700: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
d710: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
d720: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
d730: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
d740: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
d750: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d760: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
d770: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
d780: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
d790: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
d7a0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
d7b0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
d7c0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
d7d0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
d7e0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
d7f0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
d800: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
d810: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
d820: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
d830: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
d840: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
d850: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
d860: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
d870: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
d880: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
d890: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
d8a0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
d8b0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
d8c0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
d8d0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
d8e0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
d8f0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
d900: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
d910: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
d920: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
d930: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
d940: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
d950: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
d960: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
d970: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
d980: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
d990: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
d9a0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
d9b0: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
d9c0: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
d9d0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
d9e0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
d9f0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
da00: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
da10: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
da20: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
da30: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
da40: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
da50: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
da60: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
da70: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
da80: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
da90: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
daa0: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
dab0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
dac0: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
dad0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
dae0: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
daf0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
db00: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
db10: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
db20: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
db30: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
db40: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
db50: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
db60: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
db70: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
db80: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
db90: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
dba0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
dbb0: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
dbc0: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
dbd0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
dbe0: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
dbf0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
dc00: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
dc10: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
dc20: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
dc30: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
dc40: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
dc50: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
dc60: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
dc70: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
dc80: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
dc90: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
dca0: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
dcb0: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
dcc0: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
dcd0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
dce0: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
dcf0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
dd00: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
dd10: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
dd20: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
dd30: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
dd40: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
dd50: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
dd60: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
dd70: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
dd80: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
dd90: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
dda0: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
ddb0: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
ddc0: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
ddd0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
dde0: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
ddf0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
de00: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
de10: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
de20: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
de30: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
de40: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
de50: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
de60: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
de70: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
de80: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
de90: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
dea0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
deb0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
dec0: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
ded0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
dee0: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
def0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
df00: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
df10: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
df20: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
df30: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
df40: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
df50: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
df60: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
df70: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
df80: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
df90: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
dfa0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
dfb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dfc0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
dfd0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
dfe0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
dff0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
e000: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
e010: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
e020: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
e030: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
e040: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
e050: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e060: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
e070: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
e080: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
e090: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
e0a0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
e0b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e0c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e0d0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
e0e0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
e0f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e100: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e110: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
e120: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
e130: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
e140: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e150: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e160: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
e170: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
e180: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
e190: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e1a0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
e1b0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
e1c0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
e1d0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
e1e0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
e1f0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
e200: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
e210: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
e220: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
e230: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
e240: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
e250: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
e260: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
e270: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
e280: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
e290: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
e2a0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
e2b0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
e2c0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
e2d0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
e2e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
e2f0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
e300: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
e310: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e320: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
e330: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e340: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e350: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
e360: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e370: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
e380: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
e390: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
e3a0: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
e3b0: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
e3c0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
e3d0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
e3e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
e3f0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e400: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e410: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e420: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
e430: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e440: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
e450: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
e460: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
e470: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
e480: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
e490: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e4a0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e4b0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e4c0: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
e4d0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
e4e0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
e4f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e500: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
e510: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
e520: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
e530: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e540: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e550: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e560: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e570: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
e580: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
e590: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e5a0: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
e5b0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
e5c0: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
e5d0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
e5e0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
e5f0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
e600: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
e610: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
e620: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e630: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
e640: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
e650: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
e660: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
e670: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
e680: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
e690: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
e6a0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
e6b0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
e6c0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
e6d0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
e6e0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
e6f0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
e700: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
e710: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
e720: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
e730: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
e740: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
e750: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
e760: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
e770: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
e780: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e790: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
e7a0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e7b0: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
e7c0: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
e7d0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
e7e0: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
e7f0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
e800: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
e810: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
e820: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
e830: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
e840: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
e850: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
e860: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
e870: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
e880: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
e890: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e8a0: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
e8b0: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
e8c0: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
e8d0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
e8e0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
e8f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e900: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
e910: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e920: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e930: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
e940: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
e950: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
e960: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
e970: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
e980: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
e990: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
e9a0: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
e9b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
e9c0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
e9d0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
e9e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e9f0: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
ea00: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
ea10: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
ea20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
ea30: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
ea40: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
ea50: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
ea60: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
ea70: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
ea80: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
ea90: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
eaa0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
eab0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
eac0: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
ead0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
eae0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
eaf0: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
eb00: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
eb10: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
eb20: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
eb30: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
eb40: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
eb50: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
eb60: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
eb70: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
eb80: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
eb90: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
eba0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
ebb0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
ebc0: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
ebd0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
ebe0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
ebf0: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
ec00: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
ec10: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
ec20: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
ec30: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
ec40: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
ec50: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
ec60: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
ec70: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
ec80: 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20  as given on the 
ec90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
eca0: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
ecb0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
ecc0: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
ecd0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
ece0: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
ecf0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
ed00: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
ed10: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
ed20: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
ed30: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
ed40: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
ed50: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
ed60: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
ed70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
ed80: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
ed90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
eda0: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
edb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
edc0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
edd0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
ede0: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
edf0: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
ee00: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
ee10: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
ee20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
ee30: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
ee40: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
ee50: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
ee60: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
ee70: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
ee80: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
ee90: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
eea0: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
eeb0: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
eec0: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
eed0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
eee0: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
eef0: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
ef00: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
ef10: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
ef20: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
ef30: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ef40: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
ef50: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
ef60: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
ef70: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
ef80: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
ef90: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
efa0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
efb0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
efc0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
efd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
efe0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
eff0: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
f000: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
f010: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
f020: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
f030: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
f040: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
f050: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
f060: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
f070: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
f080: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
f090: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
f0a0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
f0b0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
f0c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
f0d0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
f0e0: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
f0f0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
f100: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f110: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
f120: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
f130: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
f140: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
f150: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
f160: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f170: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
f180: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
f190: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f1a0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
f1b0: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
f1c0: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
f1d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f1e0: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
f1f0: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
f200: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
f210: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
f220: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
f230: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f240: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
f250: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
f260: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
f270: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
f280: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
f290: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
f2a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f2b0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
f2c0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
f2d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f2e0: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
f2f0: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
f300: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
f310: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
f320: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f330: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
f340: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
f350: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f360: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
f370: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
f380: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
f390: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
f3a0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
f3b0: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
f3c0: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
f3d0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
f3e0: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
f3f0: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
f400: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f410: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
f420: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
f430: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
f440: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
f450: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
f460: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
f470: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
f480: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
f490: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
f4a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f4b0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
f4c0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f4d0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
f4e0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f4f0: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
f500: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f510: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
f520: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f530: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
f540: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
f550: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
f560: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
f570: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
f580: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
f590: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
f5a0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
f5b0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
f5c0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
f5d0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
f5e0: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
f5f0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
f600: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
f610: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
f620: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
f630: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f640: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f650: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
f660: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
f670: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
f680: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
f690: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
f6a0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
f6b0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
f6c0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
f6d0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f6e0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
f6f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f700: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
f710: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f720: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
f730: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
f740: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
f750: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
f760: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f770: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
f780: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
f790: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
f7a0: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
f7b0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
f7c0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
f7d0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
f7e0: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
f7f0: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
f800: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
f810: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
f820: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
f830: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
f840: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f850: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
f860: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f870: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
f880: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
f890: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
f8a0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
f8b0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
f8c0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
f8d0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
f8e0: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
f8f0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f900: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
f910: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
f920: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
f930: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f940: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
f950: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
f960: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
f970: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
f980: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
f990: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
f9a0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
f9b0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
f9c0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
f9d0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
f9e0: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
f9f0: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
fa00: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
fa10: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
fa20: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
fa30: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
fa40: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
fa50: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
fa60: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
fa70: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
fa80: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
fa90: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
faa0: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
fab0: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
fac0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
fad0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
fae0: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
faf0: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
fb00: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
fb10: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
fb20: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
fb30: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
fb40: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
fb50: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
fb60: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
fb70: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
fb80: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
fb90: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
fba0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
fbb0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
fbc0: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
fbd0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
fbe0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
fbf0: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
fc00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
fc10: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
fc20: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
fc30: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
fc40: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
fc50: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
fc60: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
fc70: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fc80: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
fc90: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
fca0: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
fcb0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
fcc0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
fcd0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
fce0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
fcf0: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
fd00: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
fd10: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
fd20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
fd30: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
fd40: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
fd50: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
fd60: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
fd70: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
fd80: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
fd90: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
fda0: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
fdb0: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
fdc0: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
fdd0: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
fde0: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
fdf0: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
fe00: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
fe10: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
fe20: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
fe30: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
fe40: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
fe50: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fe60: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
fe70: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
fe80: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
fe90: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
fea0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
feb0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
fec0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
fed0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
fee0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
fef0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
ff00: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
ff10: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
ff20: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
ff30: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
ff40: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
ff50: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
ff60: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
ff70: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
ff80: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
ff90: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ffa0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
ffb0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
ffc0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
ffd0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
ffe0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
fff0: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
10000 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10010 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
10020 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
10030 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
10040 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
10050 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
10060 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
10070 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
10080 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
10090 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
100a0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
100b0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
100c0 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
100d0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
100e0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
100f0 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
10100 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
10110 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
10120 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
10130 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
10140 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
10150 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
10160 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
10170 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
10180 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10190 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
101a0 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
101b0 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
101c0 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
101d0 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
101e0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
101f0 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
10200 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
10210 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
10220 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
10230 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
10240 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
10250 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
10260 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10270 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
10280 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
10290 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
102a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
102b0 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
102c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
102d0 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
102e0 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
102f0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
10300 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
10310 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
10320 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
10330 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
10340 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10350 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
10360 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
10370 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
10380 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
10390 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
103a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
103b0 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
103c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
103d0 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
103e0 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
103f0 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
10400 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10410 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10420 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10430 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10440 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10450 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10460 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10470 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
10480 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
10490 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
104a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
104b0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
104c0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
104d0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
104e0 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
104f0 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10500 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10510 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10520 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10530 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10540 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10550 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
10560 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10570 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
10580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
10590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
105a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
105b0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
105c0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
105d0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
105e0 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
105f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
10600 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
10610 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
10620 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10630 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
10640 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
10650 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
10660 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10670 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
10680 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10690 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
106a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
106b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
106c0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
106d0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
106e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
106f0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
10700 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
10710 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
10720 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
10730 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
10740 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10750 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
10760 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
10770 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10780 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
10790 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
107a0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
107b0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
107c0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
107d0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
107e0 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
107f0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
10800 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
10810 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
10820 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10830 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
10840 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
10850 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
10860 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
10870 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
10880 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10890 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
108a0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
108b0 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
108c0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
108d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
108e0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
108f0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10900 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
10910 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
10920 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10930 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
10940 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10950 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
10960 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10970 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10980 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
10990 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
109a0 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
109b0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
109c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
109d0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
109e0 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
109f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10a00 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10a10 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10a20 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
10a30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10a40 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
10a50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
10a60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
10a70 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
10a80 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10a90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
10aa0 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
10ab0 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
10ac0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
10ad0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10ae0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
10af0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
10b00 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
10b10 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
10b20 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
10b30 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
10b40 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
10b50 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
10b60 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10b70 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
10b80 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
10b90 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
10ba0 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
10bb0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
10bc0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
10bd0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10be0 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
10bf0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
10c00 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
10c10 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
10c20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
10c30 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
10c40 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10c50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10c60 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
10c70 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
10c80 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
10c90 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
10ca0 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
10cb0 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
10cc0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
10cd0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
10ce0 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
10cf0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
10d00 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
10d10 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
10d20 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
10d30 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
10d40 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
10d50 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
10d60 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
10d70 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
10d80 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
10d90 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
10da0 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
10db0 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
10dc0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
10dd0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
10de0 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
10df0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
10e00 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
10e10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
10e20 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
10e30 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
10e40 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
10e50 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
10e60 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
10e70 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
10e80 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
10e90 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
10ea0 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
10eb0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
10ec0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
10ed0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
10ee0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10ef0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
10f00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
10f10 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
10f20 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
10f30 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
10f40 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10f50 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
10f60 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
10f70 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
10f80 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
10f90 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
10fa0 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
10fb0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
10fc0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
10fd0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
10fe0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
10ff0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
11000 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
11010 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
11020 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
11030 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
11040 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
11050 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
11060 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
11070 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
11080 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
11090 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
110a0 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
110b0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
110c0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
110d0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
110e0 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
110f0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
11100 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
11110 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
11120 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
11130 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
11140 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
11150 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
11160 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
11170 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
11180 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
11190 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
111a0 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
111b0 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
111c0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
111d0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
111e0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
111f0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
11200 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
11210 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
11220 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
11230 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
11240 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
11250 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
11260 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
11270 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
11280 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
11290 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
112a0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
112b0 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
112c0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
112d0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
112e0 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
112f0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
11300 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
11310 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
11320 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
11330 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
11340 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
11350 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
11360 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
11370 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
11380 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11390 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
113a0 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
113b0 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
113c0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
113d0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
113e0 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
113f0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
11400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11410 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
11420 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
11430 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
11440 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11450 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11460 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11470 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
11480 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
11490 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
114a0 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
114b0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
114c0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
114d0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
114e0 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
114f0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11500 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11510 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11520 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
11530 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11540 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
11550 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
11560 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11570 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
11580 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
11590 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
115a0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
115b0 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
115c0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
115d0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
115e0 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
115f0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11600 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
11610 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
11620 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
11630 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
11640 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11650 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
11660 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11670 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
11680 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
11690 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
116a0 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
116b0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
116c0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
116d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
116e0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
116f0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11700 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
11710 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11720 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11730 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
11740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11750 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
11760 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11770 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
11780 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11790 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
117a0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
117b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
117c0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
117d0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
117e0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
117f0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11800 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
11810 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
11820 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
11830 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11840 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11850 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
11860 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
11870 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
11880 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
11890 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
118a0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
118b0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
118c0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
118d0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
118e0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
118f0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
11900 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
11910 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
11920 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
11930 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
11940 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
11950 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11960 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11970 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
11980 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
11990 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
119a0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
119b0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
119c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
119d0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
119e0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
119f0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11a00 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11a10 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11a20 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11a30 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11a40 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11a50 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11a60 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11a70 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11a80 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
11a90 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
11aa0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
11ab0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
11ac0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
11ad0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
11ae0 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
11af0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
11b00 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
11b10 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
11b20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11b30 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11b40 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11b50 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11b60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11b70 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
11b80 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
11b90 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
11ba0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
11bb0 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
11bc0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
11bd0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
11be0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11bf0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
11c00 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
11c10 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11c20 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
11c30 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
11c40 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
11c50 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11c60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11c70 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
11c80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c90 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
11ca0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
11cb0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
11cc0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
11cd0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11ce0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11cf0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11d00 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
11d10 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11d20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
11d30 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
11d40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11d50 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11d60 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
11d70 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
11d80 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
11d90 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
11da0 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
11db0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11dc0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11dd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11de0 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
11df0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
11e00 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
11e10 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
11e20 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
11e30 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
11e40 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
11e50 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
11e60 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
11e70 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
11e80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11e90 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
11ea0 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
11eb0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11ec0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11ed0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11ee0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11ef0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11f00 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11f10 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11f20 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11f30 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
11f40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
11f50 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
11f60 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
11f70 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
11f80 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11f90 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
11fa0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11fb0 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
11fc0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11fd0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11fe0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
11ff0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12000 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
12010 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12020 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12030 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12040 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12050 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12060 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12070 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
12080 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
12090 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
120a0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
120b0 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
120c0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
120d0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
120e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
120f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12100 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
12110 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
12120 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
12130 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
12140 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12150 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
12160 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
12170 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
12180 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
12190 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
121a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
121b0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
121c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
121d0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
121e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
121f0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
12200 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
12210 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
12220 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
12230 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
12240 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
12250 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
12260 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
12270 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12280 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12290 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
122a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
122b0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
122c0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
122d0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
122e0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
122f0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
12300 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
12310 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12320 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
12330 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
12340 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
12350 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
12360 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
12370 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12380 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12390 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
123a0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
123b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
123c0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
123d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
123e0 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e  IG_MALLOC option
123f0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12400 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12410 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
12420 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12430 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12440 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12450 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
12460 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12470 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12480 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12490 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
124a0 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
124b0 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
124c0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
124d0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
124e0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
124f0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
12500 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
12510 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
12520 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
12530 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12540 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
12550 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
12560 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12570 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
12580 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12590 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
125a0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
125b0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
125c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
125d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
125e0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69  G_GETMALLOC opti
125f0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12600 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12610 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
12620 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12630 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12640 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12650 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b  ucture..** The [
12660 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12670 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
12680 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
12690 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
126a0 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
126b0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
126c0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
126d0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
126e0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
126f0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12700 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
12710 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
12720 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
12730 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
12740 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
12750 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
12760 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12770 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
12780 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12790 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
127a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
127b0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
127c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
127d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
127e0 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b  TATUS option tak
127f0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
12800 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a  nt of type int,.
12810 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ** interpreted a
12820 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
12830 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
12840 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
12850 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f  ction of.** memo
12860 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12870 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
12880 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12890 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
128a0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74  e.** disabled, t
128b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
128c0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
128d0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
128e0 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
128f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12900 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
12910 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12920 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
12930 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
12940 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
12950 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
12960 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12970 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d  ite3_status64()]
12980 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
12990 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
129a0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
129b0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
129c0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
129d0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
129e0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
129f0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
12a00 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
12a10 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
12a20 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12a30 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
12a40 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
12a50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12a60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12a70 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
12a80 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
12a90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
12aa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12ab0 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70  CRATCH option sp
12ac0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12ad0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
12ae0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
12af0 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63  n use for scratc
12b00 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65  h memory.  ^(The
12b10 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
12b20 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c  uments.** to SQL
12b30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12b40 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  CH:  A pointer a
12b50 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12b60 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12b70 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
12b80 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12b90 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
12ba0 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
12bb0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
12bc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
12bd0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
12be0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
12bf0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
12c00 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20  s (N).)^.** The 
12c10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
12c20 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
12c30 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
12c40 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
12c50 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12c60 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12c70 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12c80 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74  l not use more t
12c90 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
12ca0 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
12cb0 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ad..** ^SQLite w
12cc0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73  ill never reques
12cd0 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  t a scratch buff
12ce0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
12cf0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
12d00 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12d10 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53  e size..** ^If S
12d20 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
12d30 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
12d40 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
12d50 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12d60 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12d70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12d80 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
12d90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12da0 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
12db0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
12dc0 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a  ry needed.<p>.**
12dd0 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69   ^When the appli
12de0 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20  cation provides 
12df0 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63  any amount of sc
12e00 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69  ratch memory usi
12e10 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  ng.** SQLITE_CON
12e20 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c  FIG_SCRATCH, SQL
12e30 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63  ite avoids unnec
12e40 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20  essary large.** 
12e50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c  [sqlite3_malloc|
12e60 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  heap allocations
12e70 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68  ]..** This can h
12e80 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f  elp [Robson proo
12e90 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79  f|prevent memory
12ea0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
12eb0 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61  ures] due to hea
12ec0 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69  p.** fragmentati
12ed0 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79  on in low-memory
12ee0 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
12ef0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
12f00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12f10 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
12f20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12f30 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
12f40 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
12f50 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12f60 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  CHE option speci
12f70 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
12f80 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
12f90 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
12fa0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
12fb0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
12fc0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
12fd0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
12fe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
12ff0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
13000 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
13010 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
13020 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
13030 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
13040 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
13050 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
13060 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
13070 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f  G_PCACHE2].** co
13080 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13090 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  on..** ^There ar
130a0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
130b0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
130c0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
130d0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
130e0 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
130f0 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
13100 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
13110 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
13120 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
13130 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
13140 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
13150 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
13160 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
13170 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
13180 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
13190 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35  tween 512 and 65
131a0 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65  536) plus some e
131b0 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65  xtra bytes for e
131c0 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
131d0 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72  er.  ^The number
131e0 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20   of extra bytes 
131f0 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61  needed by the pa
13200 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e  ge header.** can
13210 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
13220 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
13230 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
13240 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a  DRSZ] option .**
13250 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
13260 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69  fig()]..** ^It i
13270 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
13280 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
13290 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72  d memory,.** for
132a0 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   the sz paramete
132b0 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74  r to be larger t
132c0 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20  han necessary.  
132d0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
132e0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
132f0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
13300 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20  e aligned block 
13310 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a  of memory that.*
13320 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a  * is at least sz
13330 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
13340 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75  ry, otherwise su
13350 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
13360 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
13370 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
13380 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
13390 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
133a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
133b0 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
133c0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
133d0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
133e0 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
133f0 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
13400 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13410 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13420 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13430 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13440 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
13450 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
13460 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
13470 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
13480 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
13490 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c   storage space.<
134a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
134b0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
134c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
134d0 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
134e0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
134f0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
13500 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
13510 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
13520 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53  uffer .** that S
13530 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66  QLite will use f
13540 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
13550 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
13560 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a  ocation needs.**
13570 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
13580 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53  ovided for by [S
13590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
135a0 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51  ATCH] and.** [SQ
135b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
135c0 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20  CACHE]..** ^The 
135d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
135e0 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  AP option is onl
135f0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
13600 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13610 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72  d.** with either
13620 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13630 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c  MEMSYS3] or [SQL
13640 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
13650 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  S5] and returns.
13660 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
13670 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68  ] if invoked oth
13680 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72  erwise..** ^Ther
13690 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
136a0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
136b0 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20  CONFIG_HEAP:.** 
136c0 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
136d0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
136e0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
136f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
13700 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
13710 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
13720 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
13730 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
13740 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13750 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
13760 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
13770 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
13780 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
13790 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
137a0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
137b0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
137c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
137d0 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
137e0 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
137f0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
13800 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
13810 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
13820 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
13830 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  LL then the alte
13840 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
13850 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
13860 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
13870 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
13880 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13890 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
138a0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
138b0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
138c0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
138d0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
138e0 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
138f0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13900 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
13910 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
13920 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
13930 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
13940 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
13950 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
13960 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
13970 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13980 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
13990 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
139a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
139b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
139c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
139d0 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
139e0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
139f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
13a00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13a10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13a20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f  which is a.** po
13a30 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
13a40 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
13a50 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13a60 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
13a70 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
13a80 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61  pecifies alterna
13a90 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13aa0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
13ab0 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70   be used.** in p
13ac0 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72  lace the mutex r
13ad0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13ae0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
13af0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
13b00 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
13b10 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
13b20 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13b30 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13b40 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13b50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13b60 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13b70 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13b80 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13b90 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13ba0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13bb0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13bc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13bd0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
13be0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
13bf0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
13c00 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
13c10 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
13c20 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13c30 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13c40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13c50 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
13c60 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13c70 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
13c80 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
13c90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13ca0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
13cb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13cc0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
13cd0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13ce0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13cf0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13d00 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13d10 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
13d20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13d30 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13d40 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13d50 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13d60 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
13d70 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13d80 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
13d90 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
13da0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
13db0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
13dc0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
13dd0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
13de0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
13df0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
13e00 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13e10 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
13e20 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
13e30 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
13e40 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
13e50 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
13e60 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
13e70 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
13e80 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13e90 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13ea0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13eb0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13ec0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13ed0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13ee0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13ef0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13f00 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
13f10 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
13f20 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
13f30 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13f40 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
13f50 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
13f60 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
13f70 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13f80 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13f90 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13fa0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13fb0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
13fc0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13fd0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
13fe0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
14000 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SIDE option take
14010 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
14020 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a  that determine.*
14030 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69  * the default si
14040 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  ze of lookaside 
14050 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b  memory on each [
14060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14070 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
14080 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
14090 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
140a0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
140b0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
140c0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
140d0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
140e0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
140f0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
14100 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51  nection.)^  ^(SQ
14110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14120 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68  ASIDE.** sets th
14130 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  e <i>default</i>
14140 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
14150 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
14160 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
14170 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73  .** option to [s
14180 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14190 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
141a0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
141b0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
141c0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
141d0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
141e0 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
141f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14200 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
14210 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14220 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
14230 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14240 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
14250 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14260 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
14270 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
14280 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
14290 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
142a0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
142b0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
142c0 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72  ies.** the inter
142d0 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d  face to a custom
142e0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
142f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  ementation.)^.**
14300 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
14310 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
14320 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14330 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f  hods2] object.</
14340 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14350 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14360 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
14370 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14380 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14390 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
143a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
143b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
143c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
143d0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
143e0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
143f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14400 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
14410 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a  Lite copies of.*
14420 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61  * the current pa
14430 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
14440 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
14450 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
14460 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14470 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
14480 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14490 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
144a0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
144b0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73  IG_LOG option is
144c0 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
144d0 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  re the SQLite.**
144e0 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c   global [error l
144f0 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51  og]..** (^The SQ
14500 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
14510 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
14520 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
14530 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
14540 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
14550 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
14560 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
14570 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
14580 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
14590 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
145a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
145b0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
145c0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
145d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
145e0 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
145f0 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
14600 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
14610 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
14620 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
14630 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
14640 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
14650 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
14660 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
14670 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
14680 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
14690 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
146a0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
146b0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
146c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
146d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
146e0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
146f0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
14700 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
14710 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
14720 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14730 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
14740 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
14750 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
14760 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14770 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
14780 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
14790 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
147a0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
147b0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
147c0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
147d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
147e0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
147f0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
14800 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
14810 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
14820 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
14830 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
14840 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
14850 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
14860 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
14870 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
14880 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
14890 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
148a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
148b0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
148c0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
148d0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
148e0 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
148f0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
14900 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
14910 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
14920 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
14930 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
14940 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14950 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
14960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
14970 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
14980 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f  ITE_CONFIG_URI o
14990 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
149a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
149b0 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66   type int..** If
149c0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
149d0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
149e0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
149f0 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
14a00 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74  er is zero,.** t
14a10 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
14a20 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14a30 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
14a40 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14a50 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64  bally.** enabled
14a60 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20  , all filenames 
14a70 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
14a80 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
14a90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
14aa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
14ab0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
14ac0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
14ad0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
14ae0 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
14af0 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
14b00 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
14b10 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
14b20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
14b30 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
14b40 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
14b50 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
14b60 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
14b70 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14b80 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
14b90 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
14ba0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14bb0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
14bc0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
14bd0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
14be0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14bf0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14c00 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
14c10 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14c20 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
14c30 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
14c40 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
14c50 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
14c60 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
14c70 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
14c80 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
14c90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14ca0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14cb0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
14cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14cd0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14ce0 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  N.** <dd>^The SQ
14cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14d00 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
14d10 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14d20 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a  ingle integer.**
14d30 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14d40 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
14d50 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  s a boolean in o
14d60 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
14d70 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  r disable.** the
14d80 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
14d90 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
14da0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
14db0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
14dc0 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  izer..** ^The de
14dd0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
14de0 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
14df0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
14e00 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
14e10 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
14e20 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
14e30 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
14e40 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
14e50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
14e60 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
14e70 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
14e80 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
14e90 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
14ea0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
14eb0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
14ec0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
14ed0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
14ee0 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
14ef0 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
14f00 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
14f10 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
14f20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
14f30 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
14f40 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
14f50 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
14f60 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
14f70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
14f80 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
14f90 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
14fa0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
14fb0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
14fc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14fd0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
14fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14ff0 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
15000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15010 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
15020 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
15030 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
15040 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
15050 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
15060 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
15070 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
15080 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
15090 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
150a0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
150b0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
150c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
150d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
150e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
150f0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
15100 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
15110 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
15120 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
15130 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
15140 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
15150 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
15160 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15170 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
15180 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
15190 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
151a0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
151b0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
151c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
151d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
151e0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
151f0 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
15200 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
15210 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
15220 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
15230 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
15240 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
15250 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
15260 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
15270 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
15280 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15290 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
152a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
152b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
152c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
152d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
152e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
152f0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
15300 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
15310 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
15320 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
15330 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
15340 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
15350 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
15360 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
15370 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
15380 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
15390 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
153a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
153b0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
153c0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
153d0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
153e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
153f0 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
15400 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
15410 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
15420 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15430 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
15440 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
15450 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
15460 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
15470 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
15480 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
15490 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
154a0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
154b0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
154c0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
154d0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
154e0 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
154f0 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
15500 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15510 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
15520 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
15530 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
15540 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
15550 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
15560 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
15570 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
15580 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
15590 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
155a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
155b0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
155c0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
155d0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
155e0 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
155f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
15600 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
15610 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
15620 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
15630 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
15640 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
15650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
15660 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
15670 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
15680 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
15690 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
156a0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
156b0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
156c0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
156d0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
156e0 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62  p size.** will b
156f0 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  e silently trunc
15700 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72  ated if necessar
15710 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65  y so that it doe
15720 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65  s not exceed the
15730 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
15740 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
15750 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
15760 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
15770 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
15780 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
15790 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
157a0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
157b0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
157c0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
157d0 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
157e0 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
157f0 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
15800 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15810 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15820 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
15830 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15840 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64  2_HEAPSIZE.** <d
15850 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
15860 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15870 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  IZE option is on
15880 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
15890 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
158a0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
158b0 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  s with the [SQLI
158c0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
158d0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
158e0 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e  acro.** defined.
158f0 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   ^SQLITE_CONFIG_
15900 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74  WIN32_HEAPSIZE t
15910 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e  akes a 32-bit un
15920 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76  signed integer v
15930 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65  alue.** that spe
15940 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d  cifies the maxim
15950 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63  um size of the c
15960 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a  reated heap..**.
15970 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15980 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
15990 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
159a0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
159b0 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  RSZ.** <dd>^The 
159c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
159d0 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f  ACHE_HDRSZ optio
159e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
159f0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
15a00 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15a10 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
15a20 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74  nd writes into t
15a30 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20  hat integer the 
15a40 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a  number of extra.
15a50 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67  ** bytes per pag
15a60 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  e required for e
15a70 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c  ach page in [SQL
15a80 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
15a90 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d  ACHE]..** The am
15aa0 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70  ount of extra sp
15ab0 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e  ace required can
15ac0 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e   change dependin
15ad0 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  g on the compile
15ae0 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61  r,.** target pla
15af0 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74  tform, and SQLit
15b00 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  e version..**.**
15b10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15b20 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _PMASZ]].** <dt>
15b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
15b40 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ASZ.** <dd>^The 
15b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
15b60 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ASZ option takes
15b70 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
15b80 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
15b90 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  an unsigned inte
15ba0 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65  ger and sets the
15bb0 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69   "Minimum PMA Si
15bc0 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74  ze" for the mult
15bd0 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72  ithreaded.** sor
15be0 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65  ter to that inte
15bf0 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ger.  The defaul
15c00 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69  t minimum PMA Si
15c10 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65  ze is set by the
15c20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54  .** [SQLITE_SORT
15c30 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c  ER_PMASZ] compil
15c40 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20  e-time option.  
15c50 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20  New threads are 
15c60 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68  launched.** to h
15c70 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70  elp with sort op
15c80 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75  erations when mu
15c90 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74  ltithreaded sort
15ca0 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ing.** is enable
15cb0 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52  d (using the [PR
15cc0 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f  AGMA threads] co
15cd0 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61  mmand) and the a
15ce0 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74  mount of content
15cf0 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64  .** to be sorted
15d00 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67   exceeds the pag
15d10 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65  e size times the
15d20 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a   minimum of the.
15d30 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65  ** [PRAGMA cache
15d40 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61  _size] setting a
15d50 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a  nd this value..*
15d60 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
15d70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15d80 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
15d90 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15da0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15db0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
15dc0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
15dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15de0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
15df0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
15e00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15e10 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
15e20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
15e30 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
15e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15e50 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
15e60 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
15e70 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
15e80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15e90 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
15ea0 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
15eb0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
15ec0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15ed0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
15ee0 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
15ef0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
15f00 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
15f10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
15f20 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
15f30 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
15f40 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
15f50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15f60 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
15f70 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
15f80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15f90 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
15fa0 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
15fb0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15fc0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
15fd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15fe0 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
15ff0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16000 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
16010 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
16020 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
16030 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
16040 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
16050 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16060 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
16070 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
16080 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16090 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
160a0 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
160b0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
160c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
160d0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
160e0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
160f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16100 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
16110 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
16120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16130 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
16140 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
16150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16160 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
16170 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
16180 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
16190 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
161a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
161b0 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
161c0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
161d0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
161e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
161f0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16200 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20  DEX_SCAN 20  /* 
16210 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16220 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
16230 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a  LOG       21  /*
16240 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20   xSqllog, void* 
16250 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16260 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
16270 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c  ZE    22  /* sql
16280 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69  ite3_int64, sqli
16290 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65  te3_int64 */.#de
162a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
162b0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
162c0 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e  E      23  /* in
162d0 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69  t nByte */.#defi
162e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
162f0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20  _PCACHE_HDRSZ   
16300 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20       24  /* int 
16310 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  *psz */.#define 
16320 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
16330 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20  ASZ             
16340 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65    25  /* unsigne
16350 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a  d int szPma */..
16360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16370 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
16380 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
16390 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
163a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
163b0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
163c0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
163d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
163e0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
163f0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
16400 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
16410 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
16420 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
16430 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
16440 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16450 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
16460 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
16470 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
16480 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
16490 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
164a0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
164b0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
164c0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
164d0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
164e0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
164f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16500 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
16510 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
16520 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
16530 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16540 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
16550 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
16560 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
16570 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
16580 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
16590 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
165a0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
165b0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
165c0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
165d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
165e0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
165f0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16600 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
16610 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
16620 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
16630 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
16640 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
16650 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
16660 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
16670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16680 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
16690 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
166a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
166b0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
166c0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
166d0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
166e0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
166f0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
16700 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
16710 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
16720 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
16730 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16740 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
16750 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
16760 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
16770 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
16780 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
16790 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
167a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
167b0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
167c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
167d0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
167e0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
167f0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
16800 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
16810 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
16820 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
16830 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
16840 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16850 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
16860 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
16870 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
16880 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
16890 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
168a0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
168b0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
168c0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
168d0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
168e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
168f0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
16900 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16910 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
16920 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
16930 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
16940 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
16950 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
16960 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
16970 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
16980 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
16990 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
169a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
169b0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
169c0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
169d0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
169e0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
169f0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
16a00 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
16a10 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
16a20 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
16a30 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
16a40 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
16a50 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
16a60 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
16a70 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
16a80 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
16a90 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
16aa0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
16ab0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
16ac0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
16ad0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
16ae0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
16af0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
16b00 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
16b10 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
16b20 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
16b30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
16b40 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
16b50 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
16b60 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
16b70 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
16b80 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
16b90 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
16ba0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
16bb0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
16bc0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
16bd0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
16be0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
16bf0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
16c00 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
16c10 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
16c20 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
16c30 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
16c40 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
16c50 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
16c60 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
16c70 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
16c80 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
16c90 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
16ca0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
16cb0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
16cc0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
16cd0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
16ce0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
16cf0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
16d00 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
16d10 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
16d20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16d30 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16d40 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
16d50 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
16d60 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16d70 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
16d80 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
16d90 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
16da0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
16db0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
16dc0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
16dd0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
16de0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
16df0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
16e00 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
16e10 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
16e20 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
16e30 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
16e40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16e50 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
16e60 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
16e70 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
16e80 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
16e90 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
16ea0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
16eb0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
16ec0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
16ed0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16ee0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
16ef0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
16f00 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
16f10 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
16f20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
16f30 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
16f40 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
16f50 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
16f60 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
16f70 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16f80 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
16f90 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
16fa0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
16fb0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
16fc0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
16fd0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
16fe0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
16ff0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
17000 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
17010 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
17020 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
17030 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
17040 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
17050 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
17060 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
17070 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
17080 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
17090 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
170a0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
170b0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
170c0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
170d0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
170e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
170f0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
17100 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
17110 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
17120 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
17130 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
17140 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
17150 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
17160 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
17170 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
17180 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
17190 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
171a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
171b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
171c0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
171d0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
171e0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
171f0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
17200 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
17210 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
17220 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
17230 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
17240 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
17250 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
17260 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
17270 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
17280 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
17290 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
172a0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
172b0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
172c0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
172d0 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
172e0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
172f0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
17300 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
17310 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
17320 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
17330 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
17340 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
17350 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
17360 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
17370 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
17380 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
17390 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
173a0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
173b0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
173c0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
173d0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
173e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
173f0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
17400 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  e .** most recen
17410 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
17420 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
17430 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
17440 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
17450 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
17460 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73  ction D..** ^Ins
17470 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
17480 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
17490 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65   are not recorde
174a0 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  d..** ^If no suc
174b0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
174c0 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
174d0 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  les.** have ever
174e0 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65   occurred on the
174f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17500 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e  tion D, .** then
17510 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
17520 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
17530 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
17540 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
17550 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
17560 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
17570 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
17580 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
17590 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
175a0 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
175b0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
175c0 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
175d0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
175e0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
175f0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
17600 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
17610 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
17620 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17630 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
17640 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
17650 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
17660 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
17670 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
17680 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
17690 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
176a0 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
176b0 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
176c0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
176d0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
176e0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
176f0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
17700 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
17710 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
17720 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
17730 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
17740 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
17750 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
17760 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
17770 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
17780 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
17790 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
177a0 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
177b0 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
177c0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
177d0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
177e0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
177f0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
17800 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
17810 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
17820 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
17830 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
17840 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
17850 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
17860 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
17870 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
17880 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
17890 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
178a0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
178b0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
178c0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
178d0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
178e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
178f0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
17900 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
17910 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
17920 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
17930 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
17940 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
17950 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
17960 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
17970 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
17980 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
17990 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
179a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
179b0 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
179c0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
179d0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
179e0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
179f0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
17a00 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
17a10 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
17a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17a30 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
17a40 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17a50 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
17a60 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
17a70 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
17a80 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
17a90 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
17aa0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
17ab0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
17ac0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17ad0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
17ae0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
17af0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
17b00 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
17b10 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
17b20 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
17b30 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
17b40 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
17b50 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
17b60 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17b70 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
17b80 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
17b90 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
17ba0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17bb0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
17bc0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
17bd0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
17be0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
17bf0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
17c00 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
17c10 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
17c20 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
17c30 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
17c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
17c50 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
17c60 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
17c70 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
17c80 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
17c90 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
17ca0 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
17cb0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
17cc0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
17cd0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
17ce0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
17cf0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
17d00 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
17d10 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
17d20 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
17d30 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
17d40 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
17d50 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17d60 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
17d70 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
17d80 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
17d90 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
17da0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
17db0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
17dc0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
17dd0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
17de0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
17df0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17e00 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
17e10 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
17e20 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
17e30 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
17e40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
17e50 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
17e60 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
17e70 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
17e80 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
17e90 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
17ea0 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
17eb0 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
17ec0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
17ed0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
17ee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
17ef0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
17f00 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
17f10 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
17f20 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
17f30 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
17f40 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
17f50 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
17f60 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
17f70 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
17f80 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
17f90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
17fa0 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
17fb0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
17fc0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
17fd0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
17fe0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
17ff0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
18000 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
18010 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
18020 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
18030 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18040 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
18050 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18060 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
18070 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
18080 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
18090 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
180a0 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
180b0 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
180c0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
180d0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
180e0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
180f0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
18100 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
18110 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
18120 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
18130 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18140 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
18150 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
18160 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
18170 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
18180 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
18190 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
181a0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
181b0 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
181c0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
181d0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
181e0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
181f0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
18200 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
18210 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
18220 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
18230 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
18240 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
18250 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
18260 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
18270 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
18280 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
18290 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
182a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
182b0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
182c0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
182d0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
182e0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
182f0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
18300 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
18310 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
18320 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
18330 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
18340 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
18350 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
18360 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
18370 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
18380 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
18390 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
183a0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
183b0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
183c0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
183d0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
183e0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
183f0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
18400 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
18410 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
18420 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
18430 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
18440 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
18450 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
18460 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
18470 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
18480 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
18490 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
184a0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
184b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
184c0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
184d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
184e0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
184f0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
18500 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
18510 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
18520 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
18530 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
18540 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
18550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18560 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
18570 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
18580 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18590 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
185a0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
185b0 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
185c0 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
185d0 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
185e0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
185f0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
18600 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
18610 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
18620 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18630 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
18640 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
18650 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
18660 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
18670 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
18680 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
18690 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
186a0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
186b0 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
186c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
186d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
186e0 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
186f0 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
18700 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
18710 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
18720 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
18730 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
18740 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
18750 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
18760 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
18770 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
18780 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
18790 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
187a0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
187b0 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
187c0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
187d0 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
187e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
187f0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
18800 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
18810 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
18820 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
18830 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
18840 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
18850 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
18860 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
18870 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
18880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18890 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
188a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
188b0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
188c0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
188d0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
188e0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
188f0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
18900 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
18910 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
18920 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18930 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
18940 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
18950 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
18960 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
18970 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
18980 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
18990 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
189a0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
189b0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
189c0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
189d0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
189e0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
189f0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
18a00 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
18a10 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
18a20 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
18a30 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
18a40 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
18a50 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
18a60 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
18a70 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
18a80 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18a90 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
18aa0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
18ab0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
18ac0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
18ad0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
18ae0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
18af0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
18b00 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
18b10 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
18b20 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
18b30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18b40 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
18b50 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
18b60 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
18b70 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
18b80 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
18b90 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18ba0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
18bb0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
18bc0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
18bd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18be0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
18bf0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
18c00 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
18c10 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
18c20 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
18c30 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
18c40 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
18c50 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18c60 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
18c70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
18c80 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
18c90 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
18ca0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
18cb0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
18cc0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
18cd0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
18ce0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
18cf0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
18d00 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
18d10 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
18d20 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
18d30 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
18d40 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
18d50 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18d60 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
18d70 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
18d80 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
18d90 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
18da0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
18db0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
18dc0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
18dd0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
18de0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
18df0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
18e00 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
18e10 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
18e20 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
18e30 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
18e40 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
18e50 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
18e60 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
18e70 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
18e80 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
18e90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
18ea0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
18eb0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18ec0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18ed0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
18ee0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
18ef0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
18f00 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
18f10 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
18f20 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
18f30 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
18f40 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
18f50 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
18f60 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
18f70 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
18f80 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
18f90 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
18fa0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
18fb0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18fc0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18fd0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18fe0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
18ff0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
19000 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19010 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
19020 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
19030 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
19040 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
19050 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
19060 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
19070 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
19080 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
19090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
190a0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
190b0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
190c0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
190d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
190e0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
190f0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
19100 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
19110 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
19120 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
19130 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
19140 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
19150 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
19160 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
19170 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
19180 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
19190 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
191a0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
191b0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
191c0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
191d0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
191e0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
191f0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
19200 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
19210 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
19220 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
19230 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
19240 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
19250 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
19260 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
19270 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
19280 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
19290 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
192a0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
192b0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
192c0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
192d0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
192e0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
192f0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
19300 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
19310 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
19320 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
19330 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
19340 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
19350 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
19360 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
19370 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
19380 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
19390 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
193a0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
193b0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
193c0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
193d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
193e0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
193f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
19400 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
19410 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
19420 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
19430 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
19440 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
19450 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
19460 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
19470 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
19480 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
19490 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
194a0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
194b0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
194c0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
194d0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
194e0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
194f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
19500 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
19510 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
19520 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
19530 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
19540 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
19550 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
19560 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
19570 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
19580 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
19590 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
195a0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
195b0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
195c0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
195d0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
195e0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
195f0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
19600 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
19610 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
19620 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
19630 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19640 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
19650 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
19660 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
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 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
196a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
196b0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
196c0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
196d0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
196e0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
196f0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
19700 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
19710 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
19720 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
19730 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
19740 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
19750 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
19760 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
19770 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
19780 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
19790 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
197a0 72 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r}.**.** ^The sq
197b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
197c0 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e  er(D,X,P) routin
197d0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
197e0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  k function X.** 
197f0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
19800 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
19810 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
19820 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
19830 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61  made to access a
19840 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
19850 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
19860 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19870 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20  nection] D when 
19880 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
19890 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
198a0 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65   the table locke
198b0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
198c0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
198d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
198e0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a  ed to implement.
198f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
19900 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20  _timeout()] and 
19910 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
19920 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  eout]..**.** ^If
19930 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
19940 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
19950 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
19960 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
19970 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
19980 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
19990 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
199a0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
199b0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
199c0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
199d0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
199e0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
199f0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
19a00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
19a10 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19a20 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
19a30 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
19a40 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
19a50 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
19a60 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
19a70 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
19a80 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19a90 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
19aa0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
19ab0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
19ac0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
19ad0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
19ae0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
19af0 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72  d previously for
19b00 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
19b10 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
19b20 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
19b30 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
19b40 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
19b50 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
19b60 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
19b70 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
19b80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
19b90 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f  s returned.** to
19ba0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
19bb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
19bc0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
19bd0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
19be0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
19bf0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
19c00 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
19c10 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
19c20 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
19c30 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
19c40 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
19c50 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
19c60 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
19c70 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
19c80 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
19c90 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
19ca0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
19cb0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
19cc0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
19cd0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
19ce0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
19cf0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
19d00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
19d10 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  BUSY].** to the 
19d20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74  application inst
19d30 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
19d40 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e  the .** busy han
19d50 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
19d60 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
19d70 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
19d80 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
19d90 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
19da0 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
19db0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
19dc0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
19dd0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
19de0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
19df0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
19e00 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
19e10 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
19e20 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
19e30 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
19e40 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
19e50 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
19e60 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
19e70 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
19e80 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
19e90 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
19ea0 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
19eb0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
19ec0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
19ed0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
19ee0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
19ef0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
19f00 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
19f10 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
19f20 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
19f30 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
19f40 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
19f50 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
19f60 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
19f70 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
19f80 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
19f90 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
19fa0 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
19fb0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
19fc0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
19fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
19fe0 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
19ff0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1a000 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1a010 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1a020 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
1a030 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
1a040 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a050 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
1a060 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
1a070 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
1a080 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1a090 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74  handler.)^  ^Not
1a0a0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
1a0b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1a0c0 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76  eout()].** or ev
1a0d0 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41  aluating [PRAGMA
1a0e0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d   busy_timeout=N]
1a0f0 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65   will change the
1a100 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1a110 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20   and thus clear 
1a120 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73  any previously s
1a130 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  et busy handler.
1a140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
1a150 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
1a160 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
1a170 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
1a180 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
1a190 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1a1a0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1a1b0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20  sy handler.  In 
1a1c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
1a1d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a1e0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
1a1f0 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  t.  Any such act
1a200 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
1a210 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
1a220 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
1a230 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
1a240 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
1a250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a260 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
1a270 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
1a280 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1a290 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
1a2a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1a2b0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1a2c0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
1a2d0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
1a2e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1a2f0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1a300 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
1a310 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
1a320 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1a330 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
1a340 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
1a350 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
1a360 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
1a370 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
1a380 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
1a390 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
1a3a0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1a3b0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1a3c0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1a3d0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1a3e0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1a3f0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1a400 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1a410 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1a420 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1a430 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1a440 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1a450 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1a460 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1a470 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
1a480 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1a490 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1a4a0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1a4b0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1a4c0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1a4d0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1a4e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1a4f0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1a500 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1a510 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1a520 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1a530 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1a540 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1a550 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1a560 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1a570 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1a580 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1a590 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1a5a0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1a5b0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1a5c0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1a5d0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1a5e0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1a5f0 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1a600 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20  timeout].*/.int 
1a610 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1a620 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1a630 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1a640 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1a650 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1a660 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1a670 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
1a680 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
1a690 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
1a6a0 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
1a6b0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1a6c0 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
1a6d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
1a6e0 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
1a6f0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
1a700 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
1a710 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
1a720 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
1a730 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
1a740 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1a750 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
1a760 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
1a770 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
1a780 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
1a790 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
1a7a0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
1a7b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
1a7c0 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
1a7d0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
1a7e0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
1a7f0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
1a800 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
1a810 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
1a820 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
1a830 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
1a840 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
1a850 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
1a860 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
1a870 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
1a880 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
1a890 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
1a8a0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a8b0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1a8c0 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
1a8d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1a8e0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
1a8f0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
1a900 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
1a910 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
1a920 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
1a930 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
1a940 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1a950 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
1a960 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
1a970 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
1a980 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
1a990 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
1a9a0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
1a9b0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
1a9c0 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
1a9d0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
1a9e0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
1a9f0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
1aa00 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1aa10 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
1aa20 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
1aa30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1aa40 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
1aa50 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1aa60 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
1aa70 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
1aa80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1aa90 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
1aaa0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
1aab0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
1aac0 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
1aad0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
1aae0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
1aaf0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
1ab00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1ab10 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
1ab20 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
1ab30 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
1ab40 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
1ab50 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
1ab60 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
1ab70 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1ab80 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1ab90 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
1aba0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
1abb0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
1abc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1abd0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
1abe0 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
1abf0 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
1ac00 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
1ac10 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
1ac20 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
1ac30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1ac40 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
1ac50 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
1ac60 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
1ac70 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
1ac80 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
1ac90 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
1aca0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
1acb0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
1acc0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
1acd0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
1ace0 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
1acf0 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
1ad00 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ad10 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1ad20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ad30 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
1ad40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ad50 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
1ad60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ad70 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
1ad80 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
1ad90 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
1ada0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
1adb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
1adc0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
1add0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1ade0 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
1adf0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ae00 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
1ae10 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ae20 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
1ae30 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1ae40 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1ae50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
1ae60 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
1ae70 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
1ae80 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
1ae90 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
1aea0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1aeb0 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
1aec0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
1aed0 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
1aee0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
1aef0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1af00 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
1af10 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
1af20 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
1af30 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
1af40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1af50 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1af60 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
1af70 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
1af80 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
1af90 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
1afa0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
1afb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1afc0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
1afd0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
1afe0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
1aff0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
1b000 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
1b010 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1b020 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
1b030 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
1b040 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
1b050 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
1b060 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
1b070 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
1b080 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
1b090 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
1b0a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1b0b0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
1b0c0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
1b0d0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
1b0e0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
1b0f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1b100 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
1b110 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
1b120 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
1b130 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
1b140 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
1b150 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b160 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
1b170 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1b180 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
1b190 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
1b1a0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
1b1b0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
1b1c0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
1b1d0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
1b1e0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
1b1f0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
1b200 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
1b210 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
1b220 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
1b230 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
1b240 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
1b250 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
1b260 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
1b270 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1b280 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
1b290 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1b2a0 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  msg()]..*/.int s
1b2b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b2c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1b2d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1b2e0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1b2f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1b300 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1b310 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1b320 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1b330 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1b340 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1b350 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1b360 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1b370 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1b380 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1b390 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1b3a0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1b3b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1b3c0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1b3d0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1b3e0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1b3f0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1b400 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1b410 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1b420 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
1b430 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
1b440 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
1b450 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
1b460 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  nting Functions.
1b470 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1b480 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c  ines are work-al
1b490 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
1b4a0 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
1b4b0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
1b4c0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
1b4d0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68  C library..** Th
1b4e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64  ese routines und
1b4f0 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20  erstand most of 
1b500 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66  the common K&R f
1b510 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1b520 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20  s,.** plus some 
1b530 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73  additional non-s
1b540 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c  tandard formats,
1b550 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e   detailed below.
1b560 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f  .** Note that so
1b570 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f  me of the more o
1b580 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e  bscure formattin
1b590 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72  g options from r
1b5a0 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61  ecent.** C-libra
1b5b0 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65  ry standards are
1b5c0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1b5d0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  is implementatio
1b5e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
1b5f0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
1b600 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
1b610 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
1b620 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
1b630 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
1b640 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
1b650 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b660 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
1b670 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1b680 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
1b690 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
1b6a0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
1b6b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
1b6c0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
1b6d0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
1b6e0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
1b6f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
1b700 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1b710 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
1b720 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1b730 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
1b740 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1b750 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b760 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
1b770 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
1b780 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
1b790 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1b7a0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
1b7b0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
1b7c0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
1b7d0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
1b7e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
1b7f0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
1b800 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
1b810 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
1b820 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
1b830 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
1b840 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
1b850 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
1b860 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
1b870 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
1b880 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
1b890 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
1b8a0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
1b8b0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
1b8c0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1b8d0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
1b8e0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
1b8f0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
1b900 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1b910 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
1b920 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
1b930 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
1b940 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
1b950 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
1b960 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
1b970 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
1b980 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
1b990 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
1b9a0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
1b9b0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
1b9c0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
1b9d0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
1b9e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
1b9f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1ba00 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
1ba10 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
1ba20 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
1ba30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
1ba40 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
1ba50 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
1ba60 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ba70 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
1ba80 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
1ba90 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
1baa0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
1bab0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1bac0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
1bad0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
1bae0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
1baf0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
1bb00 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
1bb10 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
1bb20 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
1bb30 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
1bb40 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
1bb50 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
1bb60 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ters..**.** ^The
1bb70 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e   sqlite3_vsnprin
1bb80 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1bb90 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f  a varargs versio
1bba0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1bbb0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  rintf()..**.** T
1bbc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
1bbd0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
1bbe0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
1bbf0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
1bc00 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
1bc10 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
1bc20 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1bc30 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
1bc40 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
1bc50 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1bc60 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
1bc70 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
1bc80 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
1bc90 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a  Q", "%w" and "%z
1bca0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
1bcb0 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
1bcc0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
1bcd0 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
1bce0 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
1bcf0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1bd00 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1bd10 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1bd20 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1bd30 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1bd40 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1bd50 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1bd60 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1bd70 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1bd80 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1bd90 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1bda0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1bdb0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1bdc0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1bdd0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1bde0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1bdf0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1be00 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1be10 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1be20 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1be30 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1be40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1be50 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1be60 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1be70 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1be80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1be90 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1bea0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1beb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1bec0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1bed0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1bee0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1bef0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1bf00 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1bf10 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1bf20 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1bf30 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1bf40 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1bf50 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1bf60 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1bf70 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1bf80 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1bf90 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1bfa0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1bfb0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1bfc0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1bfd0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1bfe0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1bff0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c000 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c010 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1c020 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1c030 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1c040 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1c050 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c060 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1c070 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1c080 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1c090 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1c0a0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1c0b0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1c0c0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1c0d0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c0e0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1c0f0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1c100 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1c110 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c120 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1c130 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1c140 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1c150 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1c160 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1c170 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1c180 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1c190 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1c1a0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1c1b0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1c1c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1c1d0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1c1e0 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1c1f0 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1c200 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1c210 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1c220 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1c230 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1c240 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1c250 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1c260 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1c270 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1c280 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1c290 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1c2a0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1c2b0 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1c2c0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1c2d0 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1c2e0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c2f0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1c300 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1c310 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1c320 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1c330 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1c340 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1c350 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1c360 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1c370 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1c380 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1c390 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1c3a0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1c3b0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1c3c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1c3d0 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1c3e0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1c3f0 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1c400 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1c410 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22  **.** ^(The "%w"
1c420 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1c430 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20  on is like "%q" 
1c440 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65  except that it e
1c450 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20  xpects to.** be 
1c460 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
1c470 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69   double-quotes i
1c480 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65  nstead of single
1c490 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a   quotes, and it.
1c4a0 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64  ** escapes the d
1c4b0 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72  ouble-quote char
1c4c0 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  acter instead of
1c4d0 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74   the single-quot
1c4e0 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29  e.** character.)
1c4f0 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d  ^  The "%w" form
1c500 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1c510 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61   intended for sa
1c520 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a  fely inserting.*
1c530 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  * table and colu
1c540 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20  mn names into a 
1c550 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20  constructed SQL 
1c560 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
1c570 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
1c580 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
1c590 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
1c5a0 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
1c5b0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
1c5c0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
1c5d0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
1c5e0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
1c5f0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
1c600 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
1c610 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
1c620 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
1c630 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
1c640 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1c650 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
1c660 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
1c670 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1c680 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
1c690 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
1c6a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1c6b0 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  *, ...);.char *s
1c6c0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1c6d0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1c6e0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1c6f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c700 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1c710 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1c720 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1c730 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1c740 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1c750 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1c760 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1c770 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c780 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1c790 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1c7a0 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1c7b0 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1c7c0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1c7d0 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1c7e0 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1c7f0 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1c800 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1c810 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1c820 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1c830 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1c840 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1c850 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1c860 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1c870 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1c880 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1c890 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1c8a0 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1c8b0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1c8c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1c8d0 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1c8e0 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1c8f0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1c900 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1c910 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1c920 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1c930 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c940 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1c950 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1c960 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1c970 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1c980 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1c990 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1c9a0 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20  oc64(N) routine 
1c9b0 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a  works just like.
1c9c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c9d0 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  c(N) except that
1c9e0 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65   N is an unsigne
1c9f0 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  d 64-bit integer
1ca00 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1ca10 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69   signed 32-bit i
1ca20 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  nteger..**.** ^C
1ca30 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1ca40 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1ca50 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1ca60 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1ca70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ca80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1ca90 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1caa0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1cab0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1cac0 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1cad0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1cae0 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1caf0 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1cb00 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1cb10 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1cb20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1cb30 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1cb40 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1cb50 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1cb60 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1cb70 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1cb80 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1cb90 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1cba0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1cbb0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1cbc0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1cbd0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1cbe0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1cbf0 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1cc00 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1cc10 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1cc20 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1cc30 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1cc40 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1cc50 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1cc60 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1cc70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1cc80 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1cc90 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1cca0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1ccb0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ccc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ccd0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1cce0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1ccf0 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1cd00 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1cd10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f   allocation X to
1cd20 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1cd30 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
1cd40 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   X parameter to 
1cd50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cd60 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  X,N).** is a NUL
1cd70 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
1cd80 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
1cd90 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
1cda0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
1cdb0 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66  alloc(N)..** ^If
1cdc0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
1cdd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1cde0 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f  loc(X,N) is zero
1cdf0 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1ce00 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1ce10 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1ce20 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1ce30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1ce40 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  (X)..** ^sqlite3
1ce50 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1ce60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1ce70 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
1ce80 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
1ce90 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1cea0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
1ceb0 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
1cec0 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c  mory is availabl
1ced0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
1cee0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
1cef0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
1cf00 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
1cf10 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
1cf20 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1cf30 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
1cf40 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1cf50 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
1cf60 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
1cf70 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20  ealloc(X,N) and 
1cf80 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1cf90 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1cfa0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1cfb0 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1cfc0 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  ns NULL and N is
1cfd0 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
1cfe0 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c  the.** prior all
1cff0 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66  ocation is not f
1d000 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
1d010 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d020 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  64(X,N) interfac
1d030 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  es works the sam
1d040 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
1d050 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63  realloc(X,N) exc
1d060 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20  ept that N is a 
1d070 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1d080 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1d090 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73  ** of a 32-bit s
1d0a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
1d0b0 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20  *.** ^If X is a 
1d0c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d0d0 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  n previously obt
1d0e0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1d0f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  e3_malloc(),.** 
1d100 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1d110 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1d120 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  loc(), or sqlite
1d130 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74  3_realloc64(), t
1d140 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
1d150 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
1d160 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74  the size of that
1d170 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1d180 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20  on in bytes..** 
1d190 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1d1a0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1d1b0 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65  size(X) might be
1d1c0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
1d1d0 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79   number.** of by
1d1e0 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68  tes requested wh
1d1f0 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74  en X was allocat
1d200 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20  ed.  ^If X is a 
1d210 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1d220 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1d230 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65  ze(X) returns ze
1d240 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73  ro.  If X points
1d250 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68   to something th
1d260 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65  at is not.** the
1d270 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65   beginning of me
1d280 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  mory allocation,
1d290 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73   or if it points
1d2a0 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a   to a formerly.*
1d2b0 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61  * valid memory a
1d2c0 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68  llocation that h
1d2d0 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65  as now been free
1d2e0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
1d2f0 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  vior.** of sqlit
1d300 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75  e3_msize(X) is u
1d310 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73  ndefined and pos
1d320 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  sibly harmful..*
1d330 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1d340 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1d350 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73  ite3_malloc(), s
1d360 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d370 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1d380 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c  loc64(), and sql
1d390 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1d3a0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1d3b0 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1d3c0 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1d3d0 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1d3e0 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1d3f0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1d400 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1d410 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1d420 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1d430 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1d440 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1d450 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1d460 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1d470 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1d480 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1d490 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1d4a0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1d4b0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1d4c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1d4d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1d4e0 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1d4f0 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1d500 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1d510 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1d520 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1d530 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1d540 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1d550 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
1d560 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20  version 3.7.10, 
1d570 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  the Windows OS i
1d580 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1d590 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73  alled.** the sys
1d5a0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
1d5b0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
1d5c0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
1d5d0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
1d5e0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
1d5f0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
1d600 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
1d610 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
1d620 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
1d630 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
1d640 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
1d650 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
1d660 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d670 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65  errors were dete
1d680 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
1d690 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20  y were reported 
1d6a0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
1d6b0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
1d6c0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
1d6d0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
1d6e0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
1d6f0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
1d700 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
1d710 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
1d720 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d730 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
1d740 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
1d750 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
1d760 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1d770 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
1d780 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1d790 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
1d7a0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
1d7b0 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
1d7c0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
1d7d0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
1d7e0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
1d7f0 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
1d800 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
1d810 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
1d820 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
1d830 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
1d840 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
1d850 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1d860 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
1d870 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1d880 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
1d890 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1d8a0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1d8b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1d8c0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1d8d0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
1d8e0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64  3_realloc64(void
1d8f0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
1d900 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
1d910 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71  _free(void*);.sq
1d920 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c  lite3_uint64 sql
1d930 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a  ite3_msize(void*
1d940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d950 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1d960 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1d970 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1d980 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1d990 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1d9a0 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1d9b0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1d9c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d9d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1d9e0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1d9f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1da00 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1da10 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1da20 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1da30 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1da40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1da50 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1da60 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1da70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1da80 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1da90 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1daa0 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1dab0 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1dac0 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1dad0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1dae0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1daf0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1db00 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1db10 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1db20 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1db30 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1db40 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1db50 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1db60 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1db70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1db80 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1db90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1dba0 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1dbb0 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1dbc0 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1dbd0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1dbe0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1dbf0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1dc00 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1dc10 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1dc20 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1dc30 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1dc40 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1dc50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1dc60 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1dc70 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1dc80 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1dc90 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1dca0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1dcb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1dcc0 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1dcd0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1dce0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1dcf0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1dd00 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1dd10 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1dd20 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1dd30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1dd40 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1dd50 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1dd60 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1dd70 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
1dd80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1dd90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1dda0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
1ddb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1ddc0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1ddd0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1dde0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ddf0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1de00 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1de10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1de20 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1de30 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1de40 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1de50 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1de60 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1de70 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1de80 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1de90 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1dea0 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1deb0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1dec0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1ded0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1dee0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1def0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1df00 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1df10 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1df20 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1df30 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1df40 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1df50 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1df60 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1df70 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1df80 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1df90 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1dfa0 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1dfb0 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1dfc0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1dfd0 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65  ** ^The P parame
1dfe0 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c  ter can be a NUL
1dff0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1e000 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
1e010 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70  e has not been p
1e020 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64  reviously called
1e030 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69   or if the previ
1e040 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20  ous.** call had 
1e050 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  N less than one 
1e060 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
1e070 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68  r for P, then th
1e080 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65  e PRNG is.** see
1e090 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1e0a0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ness obtained fr
1e0b0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1e0c0 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20  ss method of.** 
1e0d0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1e0e0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1e0f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65  ..** ^If the pre
1e100 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
1e110 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61  is routine had a
1e120 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65  n N of 1 or more
1e130 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55   and a.** non-NU
1e140 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73  LL P then the ps
1e150 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
1e160 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
1e170 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
1e180 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
1e190 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1e1a0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
1e1b0 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
1e1c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
1e1d0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
1e1e0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
1e1f0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
1e200 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
1e210 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1e220 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1e230 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
1e240 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e250 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
1e260 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1e270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
1e280 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
1e290 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
1e2a0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
1e2b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1e2c0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
1e2d0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
1e2e0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
1e2f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e300 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1e310 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
1e320 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
1e330 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e340 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
1e350 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e360 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
1e370 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
1e380 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
1e390 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
1e3a0 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
1e3b0 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
1e3c0 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
1e3d0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
1e3e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1e3f0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
1e400 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
1e410 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
1e420 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1e430 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
1e440 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1e450 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
1e460 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
1e470 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
1e480 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
1e490 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
1e4a0 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
1e4b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
1e4c0 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
1e4d0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
1e4e0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
1e4f0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
1e500 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
1e510 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
1e520 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
1e530 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
1e540 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e550 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
1e560 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1e570 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
1e580 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
1e590 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
1e5a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1e5b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1e5c0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1e5d0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
1e5e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e5f0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1e600 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
1e610 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1e620 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e630 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
1e640 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
1e650 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
1e660 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
1e670 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1e680 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
1e690 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
1e6a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e6b0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1e6c0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1e6d0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
1e6e0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1e6f0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1e700 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
1e710 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
1e720 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
1e730 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
1e740 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1e750 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e760 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1e770 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
1e780 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
1e790 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1e7a0 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
1e7b0 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
1e7c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
1e7d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1e7e0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
1e7f0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
1e800 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1e810 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
1e820 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
1e830 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
1e840 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
1e850 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
1e860 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
1e870 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
1e880 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1e890 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
1e8a0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
1e8b0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
1e8c0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1e8d0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
1e8e0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1e8f0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
1e900 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
1e910 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1e920 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1e930 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
1e940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e950 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
1e960 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
1e970 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
1e980 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
1e990 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1e9a0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
1e9b0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
1e9c0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
1e9d0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
1e9e0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
1e9f0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
1ea00 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
1ea10 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
1ea20 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
1ea30 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
1ea40 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
1ea50 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
1ea60 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1ea70 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
1ea80 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1ea90 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
1eaa0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1eab0 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
1eac0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
1ead0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
1eae0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
1eaf0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
1eb00 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
1eb10 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
1eb20 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
1eb30 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
1eb40 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
1eb50 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1eb60 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
1eb70 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
1eb80 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
1eb90 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
1eba0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1ebb0 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
1ebc0 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
1ebd0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
1ebe0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
1ebf0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
1ec00 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
1ec10 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
1ec20 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
1ec30 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
1ec40 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
1ec50 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
1ec60 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
1ec70 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
1ec80 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
1ec90 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
1eca0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
1ecb0 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
1ecc0 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
1ecd0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
1ece0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
1ecf0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
1ed00 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
1ed10 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
1ed20 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
1ed30 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
1ed40 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
1ed50 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
1ed60 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
1ed70 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1ed80 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
1ed90 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
1eda0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
1edb0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
1edc0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
1edd0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
1ede0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
1edf0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
1ee00 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
1ee10 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
1ee20 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
1ee30 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
1ee40 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1ee50 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
1ee60 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
1ee70 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
1ee80 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
1ee90 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
1eea0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
1eeb0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
1eec0 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
1eed0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
1eee0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
1eef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1ef00 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
1ef10 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
1ef20 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1ef30 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
1ef40 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
1ef50 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
1ef60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
1ef70 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
1ef80 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
1ef90 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
1efa0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
1efb0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
1efc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1efd0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1efe0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1eff0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1f000 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1f010 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1f020 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
1f030 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
1f040 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1f050 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f060 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1f070 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1f080 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1f090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1f0a0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1f0b0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1f0c0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1f0d0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
1f0e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f0f0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
1f100 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
1f110 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1f120 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
1f130 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
1f140 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
1f150 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
1f160 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
1f170 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
1f180 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
1f190 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
1f1a0 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
1f1b0 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
1f1c0 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
1f1d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1f1e0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
1f1f0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
1f200 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f210 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
1f220 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
1f230 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1f240 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
1f250 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
1f260 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
1f270 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
1f280 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
1f290 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f2a0 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
1f2b0 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
1f2c0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1f2d0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
1f2e0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
1f2f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f300 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
1f310 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
1f320 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
1f330 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f340 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
1f350 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
1f360 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
1f370 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
1f380 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1f390 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1f3a0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
1f3b0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
1f3c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1f3d0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
1f3e0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1f3f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1f400 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1f410 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
1f420 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
1f430 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
1f440 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
1f450 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
1f460 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
1f470 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
1f480 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
1f490 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
1f4a0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
1f4b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1f4c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1f4d0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
1f4e0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
1f4f0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1f500 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1f510 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
1f520 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
1f530 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66   used as a [conf
1f540 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  lict resolution 
1f550 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  mode].** returne
1f560 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  d from the [sqli
1f570 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1f580 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1f590 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1f5a0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1f5b0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1f5c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1f5d0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1f5e0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1f5f0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1f600 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1f610 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1f620 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1f630 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1f640 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1f650 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1f660 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1f670 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1f680 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1f690 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f6a0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1f6b0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1f6c0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1f6d0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1f6e0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1f6f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1f700 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1f710 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1f720 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1f730 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1f740 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1f750 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1f760 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1f770 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1f780 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f790 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1f7a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1f7b0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1f7c0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1f7d0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1f7e0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1f7f0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1f800 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1f810 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1f820 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1f830 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1f840 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1f850 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1f860 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1f870 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1f880 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1f890 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1f8a0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1f8b0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1f8c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f8d0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1f8e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1f8f0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1f900 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1f910 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1f920 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1f930 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1f940 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1f950 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1f960 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1f970 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1f980 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1f990 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1f9a0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1f9b0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1f9c0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1f9d0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1f9e0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1f9f0 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1fa00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fa10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1fa20 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1fa30 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1fa40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fa50 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1fa60 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1fa70 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1fa80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1fa90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1faa0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1fab0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1fac0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1fad0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fae0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1faf0 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1fb00 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1fb10 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1fb20 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1fb30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fb40 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1fb50 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1fb60 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1fb70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1fb80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fb90 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1fba0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1fbb0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1fbc0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1fbd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1fbe0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1fbf0 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1fc00 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1fc10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fc20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1fc30 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1fc40 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1fc50 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1fc60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1fc70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1fc80 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1fc90 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1fca0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fcb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fcc0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1fcd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1fce0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1fcf0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1fd00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fd10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1fd20 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1fd30 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1fd40 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1fd50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fd60 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1fd70 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1fd80 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1fd90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fda0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fdb0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1fdc0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1fdd0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1fde0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1fdf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fe00 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1fe10 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1fe20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fe30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fe40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fe50 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1fe60 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1fe70 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1fe80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fe90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fea0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1feb0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1fec0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1fed0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fee0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fef0 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1ff00 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1ff10 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1ff20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ff30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ff40 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1ff50 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1ff60 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1ff70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ff80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1ff90 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1ffa0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1ffb0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ffc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ffd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1ffe0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1fff0 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
20000 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
20010 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
20020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
20030 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
20040 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
20050 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
20060 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
20070 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
20080 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
20090 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
200a0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
200b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
200c0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
200d0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
200e0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
200f0 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
20100 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20110 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
20120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20130 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
20140 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
20150 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20160 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
20170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
20180 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
20190 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
201a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
201b0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
201c0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
201d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
201e0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
201f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20200 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
20210 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
20220 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
20230 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
20240 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20250 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
20260 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
20270 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20280 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20290 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
202a0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
202b0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
202c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
202d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
202e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
202f0 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
20300 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
20310 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20320 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
20330 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20340 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
20350 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
20360 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20370 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
20380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20390 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
203a0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
203b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
203c0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
203d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
203e0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
203f0 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
20400 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
20410 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
20420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20430 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
20440 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
20450 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
20460 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
20470 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
20480 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
20490 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
204a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
204b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
204c0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
204d0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
204e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
204f0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
20500 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
20510 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
20520 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
20530 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
20540 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
20550 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
20560 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
20570 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
20580 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
20590 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
205a0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
205b0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
205c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
205d0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
205e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
205f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20600 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
20610 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
20620 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
20630 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
20640 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
20650 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
20660 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
20670 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
20680 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
20690 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
206a0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
206b0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
206c0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
206d0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
206e0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
206f0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
20700 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
20710 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
20720 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
20730 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
20740 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
20750 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
20760 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
20770 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
20780 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
20790 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
207a0 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
207b0 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
207c0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
207d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
207e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
207f0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
20800 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
20810 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
20820 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
20830 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
20840 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
20850 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
20860 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
20870 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
20880 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
20890 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
208a0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
208b0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
208c0 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
208d0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
208e0 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
208f0 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
20900 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
20910 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
20920 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
20930 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
20940 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
20950 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
20960 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
20970 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
20980 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
20990 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
209a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
209b0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
209c0 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
209d0 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
209e0 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
209f0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
20a00 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
20a10 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
20a20 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
20a30 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
20a40 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
20a50 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20a60 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69  f SQLite..*/.voi
20a70 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
20a80 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
20a90 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
20aa0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
20ab0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
20ac0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
20ad0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
20ae0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
20af0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
20b00 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
20b10 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
20b20 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
20b30 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
20b40 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
20b50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
20b60 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
20b70 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
20b80 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
20b90 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
20ba0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
20bb0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
20bc0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
20bd0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
20be0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
20bf0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
20c00 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
20c10 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
20c20 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
20c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
20c40 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
20c50 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
20c60 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
20c70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
20c80 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
20c90 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
20ca0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
20cb0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
20cc0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
20cd0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
20ce0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20cf0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
20d00 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
20d10 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
20d20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
20d30 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
20d40 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
20d50 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
20d60 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
20d70 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
20d80 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
20d90 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
20da0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
20db0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
20dc0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
20dd0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
20de0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
20df0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
20e00 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
20e10 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
20e20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
20e30 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
20e40 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
20e50 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
20e60 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
20e70 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
20e80 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
20e90 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20ea0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
20eb0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
20ec0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
20ed0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
20ee0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
20ef0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
20f00 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
20f10 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
20f20 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
20f30 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
20f40 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
20f50 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
20f60 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
20f70 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
20f80 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
20f90 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
20fa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
20fb0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
20fc0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
20fd0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
20fe0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
20ff0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21000 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
21010 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
21020 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
21030 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
21040 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
21050 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
21060 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
21070 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
21080 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
21090 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
210a0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
210b0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
210c0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
210d0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
210e0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
210f0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
21100 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
21110 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
21120 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
21130 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
21140 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
21150 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
21160 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
21170 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
21180 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
21190 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
211a0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
211b0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
211c0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
211d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
211e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
211f0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
21200 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
21210 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
21220 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
21230 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
21240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
21250 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
21260 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
21270 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
21280 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
21290 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
212a0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
212b0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
212c0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
212d0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
212e0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
212f0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
21300 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
21310 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
21320 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
21330 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
21340 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
21350 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21360 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
21370 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
21380 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
21390 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
213a0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
213b0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
213c0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
213d0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
213e0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
213f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
21400 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
21410 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
21420 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
21430 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
21440 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
21450 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
21460 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
21470 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
21480 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
21490 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
214a0 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20  t encoding will 
214b0 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74  be UTF-8 for dat
214c0 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75  abases created u
214d0 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
214e0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
214f0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54  3_open_v2().  ^T
21500 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
21510 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65  ing for database
21520 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69  s.** created usi
21530 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  ng sqlite3_open1
21540 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  6() will be UTF-
21550 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
21560 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
21570 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
21580 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
21590 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
215a0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
215b0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
215c0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
215d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
215e0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
215f0 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
21600 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
21610 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
21620 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
21630 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
21640 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
21650 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
21660 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
21670 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
21680 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
21690 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
216a0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
216b0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
216c0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
216d0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
216e0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
216f0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
21700 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
21710 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
21720 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
21730 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
21740 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
21750 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
21760 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
21770 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
21780 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
21790 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
217a0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
217b0 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
217c0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
217d0 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
217e0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
217f0 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
21800 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
21810 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
21820 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
21830 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
21840 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
21850 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
21860 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
21870 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
21880 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
21890 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
218a0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
218b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
218c0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
218d0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
218e0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
218f0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
21900 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
21910 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
21920 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
21930 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
21940 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21950 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
21960 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
21970 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
21980 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
21990 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
219a0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
219b0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
219c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
219d0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
219e0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
219f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
21a00 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21a10 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
21a20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
21a30 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
21a40 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
21a50 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
21a60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
21a70 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
21a80 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
21a90 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
21aa0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
21ab0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
21ac0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
21ad0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
21ae0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
21af0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
21b00 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
21b10 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
21b20 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
21b30 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
21b40 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
21b50 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
21b60 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
21b70 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
21b80 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
21b90 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
21ba0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
21bb0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
21bc0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21bd0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
21be0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
21bf0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
21c00 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
21c10 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
21c20 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
21c30 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
21c40 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
21c50 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
21c60 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
21c70 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
21c80 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
21c90 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21ca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
21cb0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
21cc0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
21cd0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
21ce0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
21cf0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
21d00 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
21d10 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
21d20 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
21d30 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
21d40 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
21d50 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
21d60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
21d70 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
21d80 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
21d90 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
21da0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
21db0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
21dc0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
21dd0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
21de0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
21df0 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
21e00 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
21e10 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
21e20 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
21e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21e40 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
21e50 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
21e60 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
21e70 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
21e80 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
21e90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
21ea0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21eb0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
21ec0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
21ed0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
21ee0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
21ef0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
21f00 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
21f10 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
21f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21f30 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
21f40 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
21f50 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
21f60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
21f70 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
21f80 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
21f90 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
21fa0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
21fb0 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
21fc0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
21fd0 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
21fe0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
21ff0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
22000 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
22010 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
22020 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
22030 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
22040 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22050 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
22060 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
22070 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
22080 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
22090 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
220a0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
220b0 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
220c0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
220d0 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
220e0 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
220f0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
22100 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
22110 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
22120 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
22130 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
22140 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
22150 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
22160 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
22170 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
22180 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
22190 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
221a0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
221b0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
221c0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
221d0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
221e0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
221f0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
22200 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
22210 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
22220 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
22230 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22240 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
22250 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
22260 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
22270 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
22280 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
22290 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
222a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
222b0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
222c0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
222d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
222e0 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
222f0 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
22300 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
22310 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
22320 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
22330 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
22340 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
22350 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
22360 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
22370 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
22380 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
22390 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
223a0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
223b0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
223c0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
223d0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
223e0 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
223f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
22400 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
22410 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
22420 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
22430 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
22440 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
22450 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
22460 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
22470 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
22480 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
22490 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
224a0 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
224b0 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
224c0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
224d0 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
224e0 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
224f0 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
22500 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
22510 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
22520 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
22530 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
22540 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
22550 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
22560 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
22570 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
22580 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
22590 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
225a0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
225b0 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
225c0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
225d0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
225e0 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
225f0 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
22600 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
22610 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
22620 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
22630 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
22640 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
22650 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
22660 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
22670 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
22680 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
22690 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
226a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
226b0 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
226c0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
226d0 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
226e0 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
226f0 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
22700 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
22710 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22720 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
22730 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
22740 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
22750 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
22760 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
22770 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
22780 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
22790 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
227a0 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
227b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
227c0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
227d0 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73  .** ^(On windows
227e0 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
227f0 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
22800 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
22810 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
22820 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
22830 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  ").)^.**.** [[co
22840 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
22850 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
22860 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
22870 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
22880 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
22890 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
228a0 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
228b0 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
228c0 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
228d0 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
228e0 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
228f0 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62  SQLite and its b
22900 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20  uilt-in [VFSes] 
22910 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
22920 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79   following query
22930 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
22940 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
22950 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
22960 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
22970 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
22980 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
22990 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
229a0 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
229b0 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
229c0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
229d0 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
229e0 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
229f0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
22a00 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
22a10 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
22a20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
22a30 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
22a40 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
22a50 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
22a60 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
22a70 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
22a80 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
22a90 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
22aa0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
22ab0 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
22ac0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
22ad0 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
22ae0 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
22af0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
22b00 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
22b10 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
22b20 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
22b30 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
22b40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
22b50 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
22b60 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
22b70 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
22b80 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22b90 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
22ba0 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20  "ro", "rw",.**  
22bb0 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65     "rwc", or "me
22bc0 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e  mory". Attemptin
22bd0 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
22be0 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
22bf0 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f  s.**     an erro
22c00 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
22c10 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
22c20 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
22c30 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
22c40 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
22c50 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
22c60 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
22c70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
22c80 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
22c90 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
22ca0 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
22cb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
22cc0 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  pen_v2(). ^If th
22cd0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
22ce0 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
22cf0 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
22d00 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22d10 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
22d20 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
22d30 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
22d40 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
22d50 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
22d60 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
22d70 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
22d80 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
22d90 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
22da0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
22db0 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
22dc0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
22dd0 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
22de0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
22df0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
22e00 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
22e10 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
22e20 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
22e30 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
22e40 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
22e50 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
22e60 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
22e70 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
22e80 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
22e90 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
22ea0 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
22eb0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
22ec0 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
22ed0 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
22ee0 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
22ef0 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
22f00 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
22f10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
22f20 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
22f30 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
22f40 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
22f50 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
22f60 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
22f70 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
22f80 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
22f90 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
22fa0 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
22fb0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
22fc0 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
22fd0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
22fe0 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
22ff0 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
23000 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
23010 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23020 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
23030 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
23040 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
23050 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
23060 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
23070 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
23080 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
23090 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
230a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
230b0 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
230c0 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
230d0 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
230e0 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
230f0 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
23100 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
23110 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79  ior requested by
23120 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
23130 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
23140 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
23150 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
23160 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20  CHE flag..**.** 
23170 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62   <li> <b>psow</b
23180 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72  >: ^The psow par
23190 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73  ameter indicates
231a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
231b0 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65  the.**     [powe
231c0 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d  rsafe overwrite]
231d0 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f   property does o
231e0 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79  r does not apply
231f0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73   to the.**     s
23200 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20  torage media on 
23210 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61  which the databa
23220 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e  se file resides.
23230 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
23240 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65  nolock</b>: ^The
23250 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65   nolock paramete
23260 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
23270 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a  uery parameter.*
23280 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73  *     which if s
23290 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65  et disables file
232a0 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c   locking in roll
232b0 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64  back journal mod
232c0 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20  es.  This.**    
232d0 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61   is useful for a
232e0 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62  ccessing a datab
232f0 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73  ase on a filesys
23300 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  tem that does no
23310 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74  t.**     support
23320 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69   locking.  Cauti
23330 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f  on:  Database co
23340 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72  rruption might r
23350 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20  esult if two.** 
23360 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63      or more proc
23370 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74  esses write to t
23380 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
23390 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20   and any one of 
233a0 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f  those.**     pro
233b0 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f  cesses uses nolo
233c0 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ck=1..**.**  <li
233d0 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f  > <b>immutable</
233e0 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62  b>: ^The immutab
233f0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  le parameter is 
23400 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a  a boolean query.
23410 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72  **     parameter
23420 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
23430 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
23440 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64  e file is stored
23450 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d   on.**     read-
23460 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68  only media.  ^Wh
23470 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20  en immutable is 
23480 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75  set, SQLite assu
23490 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
234a0 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c      database fil
234b0 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  e cannot be chan
234c0 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70  ged, even by a p
234d0 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68  rocess with high
234e0 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c  er.**     privil
234f0 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ege, and so the 
23500 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
23510 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64  ed read-only and
23520 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20   all locking.** 
23530 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64      and change d
23540 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61  etection is disa
23550 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20  bled.  Caution: 
23560 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75  Setting the immu
23570 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f  table.**     pro
23580 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62  perty on a datab
23590 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f  ase file that do
235a0 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67  es in fact chang
235b0 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20  e can result.** 
235c0 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74      in incorrect
235d0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61   query results a
235e0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  nd/or [SQLITE_CO
235f0 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a  RRUPT] errors..*
23600 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20  *     See also: 
23610 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d  [SQLITE_IOCAP_IM
23620 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20  MUTABLE]..**    
23630 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a     .** </ul>.**.
23640 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
23650 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
23660 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
23670 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
23680 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
23690 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
236a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
236b0 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
236c0 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
236d0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
236e0 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
236f0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
23700 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
23710 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
23720 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
23730 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
23740 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
23750 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
23760 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
23770 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
23780 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
23790 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
237a0 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
237b0 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
237c0 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
237d0 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
237e0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
237f0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23800 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
23810 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
23820 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
23830 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
23840 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
23850 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
23860 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
23870 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
23880 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
23890 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
238a0 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
238b0 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
238c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
238d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
238e0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
238f0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
23900 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
23910 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
23920 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
23930 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
23940 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
23950 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
23960 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
23970 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
23980 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
23990 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
239a0 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
239b0 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
239c0 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
239d0 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
239e0 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
239f0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
23a00 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
23a10 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
23a20 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
23a30 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
23a40 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
23a50 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
23a60 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
23a70 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
23a80 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
23a90 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
23aa0 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
23ab0 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
23ac0 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
23ad0 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
23ae0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
23af0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
23b00 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
23b10 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
23b20 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
23b30 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
23b40 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
23b50 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
23b60 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
23b70 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
23b80 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
23b90 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
23ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
23bb0 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
23bc0 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
23bd0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
23be0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
23bf0 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c  s=unix-dotfile <
23c00 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
23c10 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
23c20 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
23c30 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
23c40 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c  VFS "unix-dotfil
23c50 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  e".**          t
23c60 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c  hat uses dot-fil
23c70 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70  es in place of p
23c80 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f  osix advisory lo
23c90 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cking..** <tr><t
23ca0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
23cb0 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74  mode=readonly <t
23cc0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23cd0 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f  An error. "reado
23ce0 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61  nly" is not a va
23cf0 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74  lid option for t
23d00 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65  he "mode" parame
23d10 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ter..** </table>
23d20 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61  .**.** ^URI hexa
23d30 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
23d40 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61  equences (%HH) a
23d50 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74  re supported wit
23d60 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64  hin the path and
23d70 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  .** query compon
23d80 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41  ents of a URI. A
23d90 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
23da0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e  ape sequence con
23db0 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65  sists of a.** pe
23dc0 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22  rcent sign - "%"
23dd0 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65   - followed by e
23de0 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64  xactly two hexad
23df0 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a  ecimal digits .*
23e00 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20  * specifying an 
23e10 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65  octet value. ^Be
23e20 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72  fore the path or
23e30 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
23e40 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69  s of a.** URI fi
23e50 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72  lename are inter
23e60 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65  preted, they are
23e70 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
23e80 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a  TF-8 and all .**
23e90 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
23ea0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65  ape sequences re
23eb0 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67  placed by a sing
23ec0 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69  le byte containi
23ed0 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73  ng the.** corres
23ee0 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49  ponding octet. I
23ef0 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67  f this process g
23f00 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61  enerates an inva
23f10 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  lid UTF-8 encodi
23f20 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  ng,.** the resul
23f30 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
23f40 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
23f50 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
23f60 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
23f70 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
23f80 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
23f90 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
23fa0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
23fb0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
23fc0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
23fd0 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
23fe0 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
23ff0 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
24000 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
24010 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
24020 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
24030 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
24040 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
24050 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
24060 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
24070 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
24080 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
24090 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
240a0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
240b0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
240c0 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
240d0 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
240e0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
240f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24100 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
24110 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65  v2().  Otherwise
24120 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
24130 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
24140 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
24150 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
24160 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65  y fail..**.** Se
24170 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
24180 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d  _temp_directory]
24190 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
241a0 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
241b0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
241c0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
241d0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
241e0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
241f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
24200 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
24210 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
24220 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
24230 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
24240 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
24250 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
24260 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
24270 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
24280 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
24290 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
242a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
242b0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
242c0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
242d0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
242e0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
242f0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
24300 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
24310 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
24320 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
24330 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
24340 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
24350 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
24360 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
24370 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
24380 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
24390 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
243a0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
243b0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
243c0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
243d0 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
243e0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
243f0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
24400 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
24410 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
24420 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
24430 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
24440 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
24450 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
24460 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
24470 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
24480 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24490 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
244a0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
244b0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
244c0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
244d0 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
244e0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
244f0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
24500 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
24510 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
24520 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
24530 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
24540 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
24550 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
24560 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
24570 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
24580 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
24590 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
245a0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
245b0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
245c0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
245d0 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
245e0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
245f0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
24600 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
24610 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
24620 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24630 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
24640 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
24650 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
24660 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
24670 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24680 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
24690 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
246a0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
246b0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
246c0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
246d0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
246e0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
246f0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
24700 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
24710 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
24720 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
24730 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
24740 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
24750 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
24760 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24770 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
24780 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
24790 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
247a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
247b0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
247c0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
247d0 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
247e0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
247f0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
24800 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
24810 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
24820 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24830 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
24840 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
24850 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
24860 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24870 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
24880 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
24890 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
248a0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
248b0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
248c0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
248d0 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
248e0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
248f0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
24900 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
24910 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
24920 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
24930 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
24940 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24950 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
24960 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
24970 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
24980 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
24990 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
249a0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
249b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
249c0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
249d0 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
249e0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
249f0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
24a00 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
24a10 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
24a20 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
24a30 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
24a40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
24a50 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
24a60 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
24a70 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
24a80 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
24a90 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
24aa0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24ab0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
24ac0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
24ad0 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
24ae0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
24af0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24b00 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
24b10 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
24b20 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
24b30 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
24b40 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
24b50 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
24b60 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
24b70 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
24b80 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
24b90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
24ba0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
24bb0 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
24bc0 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
24bd0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
24be0 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
24bf0 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
24c00 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
24c10 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
24c20 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71  nt bDefault);.sq
24c30 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
24c40 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
24c50 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
24c60 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
24c70 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
24c80 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
24c90 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
24ca0 65 73 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  es.**.** ^If the
24cb0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
24cc0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
24cd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
24ce0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
24cf0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
24d00 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
24d10 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
24d20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
24d30 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
24d40 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
24d50 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
24d60 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
24d70 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
24d80 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
24d90 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
24da0 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
24db0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
24dc0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
24dd0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
24de0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
24df0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
24e00 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
24e10 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
24e20 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
24e30 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
24e40 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
24e50 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24e60 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
24e70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24e80 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
24e90 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
24ea0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
24eb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
24ec0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
24ed0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
24ee0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
24ef0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
24f00 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
24f10 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
24f20 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
24f30 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
24f40 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
24f50 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
24f60 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
24f70 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
24f80 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
24f90 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
24fa0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
24fb0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
24fc0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
24fd0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
24fe0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
24ff0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
25000 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
25010 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
25020 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
25030 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
25040 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
25050 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25060 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
25070 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
25080 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
25090 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
250a0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
250b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
250c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
250d0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
250e0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
250f0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
25100 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
25110 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
25120 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
25130 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
25140 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
25150 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
25160 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
25170 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
25180 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
25190 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
251a0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
251b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
251c0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
251d0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
251e0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
251f0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
25200 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
25210 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
25220 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
25230 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
25240 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
25250 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
25260 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
25270 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
25280 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
25290 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
252a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
252b0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
252c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
252d0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
252e0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
252f0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
25300 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
25310 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
25320 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
25330 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
25340 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
25350 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
25360 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
25370 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
25380 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
25390 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
253a0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
253b0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
253c0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
253d0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
253e0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
253f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
25400 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
25410 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
25420 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
25430 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
25440 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
25450 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
25460 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
25470 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
25480 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
25490 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
254a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
254b0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
254c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
254d0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
254e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
254f0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
25500 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25510 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
25520 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
25530 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
25540 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
25550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
25560 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
25570 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
25580 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
25590 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
255a0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
255b0 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
255c0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
255d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
255e0 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
255f0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
25600 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
25610 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
25620 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
25630 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
25640 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
25650 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
25660 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
25670 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
25680 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25690 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
256a0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
256b0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
256c0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
256d0 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
256e0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
256f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
25700 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
25710 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
25720 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
25730 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
25740 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
25750 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
25760 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
25770 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
25780 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
25790 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
257a0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
257b0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
257c0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
257d0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
257e0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
257f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
25800 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
25810 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
25820 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
25830 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
25840 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
25850 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
25860 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
25870 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
25880 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
25890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
258a0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
258b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
258c0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
258d0 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
258e0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
258f0 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
25900 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
25910 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
25920 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
25930 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
25940 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
25950 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
25960 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
25970 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
25980 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
25990 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
259a0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
259b0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
259c0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
259d0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
259e0 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
259f0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
25a00 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
25a10 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
25a20 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
25a30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
25a40 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
25a50 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
25a60 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
25a70 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
25a80 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
25a90 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
25aa0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
25ab0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
25ac0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
25ad0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
25ae0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
25af0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
25b00 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
25b10 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
25b20 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
25b30 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
25b40 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
25b50 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
25b60 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
25b70 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
25b80 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
25b90 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
25ba0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
25bb0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
25bc0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
25bd0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
25be0 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
25bf0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
25c00 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
25c10 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
25c20 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
25c30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25c40 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
25c50 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
25c60 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
25c70 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
25c80 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
25c90 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
25ca0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
25cb0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
25cc0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
25cd0 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
25ce0 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
25cf0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
25d00 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
25d10 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
25d20 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
25d30 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
25d40 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
25d50 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
25d60 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
25d70 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
25d80 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
25d90 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
25da0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
25db0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
25dc0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
25dd0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
25de0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
25df0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
25e00 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
25e10 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
25e20 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
25e30 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
25e40 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
25e50 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
25e60 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
25e70 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
25e80 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
25e90 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
25ea0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
25eb0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
25ec0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
25ed0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
25ee0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
25ef0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
25f00 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
25f10 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
25f20 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
25f30 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
25f40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
25f50 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
25f60 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
25f70 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
25f80 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
25f90 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
25fa0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
25fb0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
25fc0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
25fd0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
25fe0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
25ff0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
26000 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
26010 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
26020 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
26030 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
26040 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
26050 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
26060 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
26070 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
26080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
26090 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
260a0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
260b0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
260c0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
260d0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
260e0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
260f0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
26100 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
26110 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
26120 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
26130 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
26140 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
26150 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
26160 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
26170 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
26180 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
26190 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
261a0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
261b0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
261c0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
261d0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
261e0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
261f0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
26200 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26210 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
26220 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26230 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
26240 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
26250 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
26260 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
26270 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26280 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
26290 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
262a0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
262b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
262c0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
262d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
262e0 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
262f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26300 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
26310 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26320 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
26330 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26340 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
26350 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
26360 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
26370 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
26380 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
26390 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
263a0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
263b0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
263c0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
263d0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
263e0 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
263f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26400 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
26410 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26420 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
26430 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26440 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
26450 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
26460 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
26470 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26480 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
26490 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
264a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
264b0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
264c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
264d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
264e0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
264f0 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
26500 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
26510 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26520 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
26530 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26540 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
26550 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26560 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
26570 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
26580 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
26590 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
265a0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
265b0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
265c0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
265d0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
265e0 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
265f0 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
26600 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
26610 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
26620 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
26630 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26640 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
26650 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26660 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
26670 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26680 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26690 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
266a0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
266b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
266c0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
266d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
266e0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
266f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26700 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26710 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
26720 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
26730 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
26740 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
26750 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
26760 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
26770 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
26780 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
26790 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
267a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
267b0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
267c0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
267d0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
267e0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
267f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26800 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26810 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
26820 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
26830 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
26840 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26850 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
26860 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
26870 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
26880 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
26890 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
268a0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
268b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
268c0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
268d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
268e0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
268f0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
26900 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
26910 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26920 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
26930 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
26940 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
26950 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
26960 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26970 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
26980 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
26990 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
269a0 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
269b0 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
269c0 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
269d0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
269e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
269f0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
26a00 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
26a10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
26a20 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
26a30 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
26a40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26a50 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
26a60 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
26a70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26a80 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
26a90 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
26aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26ab0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
26ac0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
26ad0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26ae0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
26af0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
26b00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26b10 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
26b20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
26b30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26b40 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
26b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
26b60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26b70 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
26b80 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
26b90 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
26ba0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
26bb0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
26bc0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
26bd0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
26be0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
26bf0 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
26c00 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
26c10 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
26c20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
26c30 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
26c40 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
26c50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
26c60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
26c70 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
26c80 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
26c90 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
26ca0 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
26cb0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
26cc0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
26cd0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
26ce0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
26cf0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
26d00 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
26d10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26d20 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
26d30 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
26d40 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
26d50 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
26d60 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
26d70 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
26d80 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
26d90 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
26da0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
26db0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
26dc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
26dd0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
26de0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
26df0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
26e00 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
26e10 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
26e20 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
26e30 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
26e40 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
26e50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
26e60 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
26e70 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
26e80 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
26e90 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26ea0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
26eb0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
26ec0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
26ed0 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
26ee0 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
26ef0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
26f00 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
26f10 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
26f20 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
26f30 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
26f40 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
26f50 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
26f60 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
26f70 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
26f80 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
26f90 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
26fa0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
26fb0 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
26fc0 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
26fd0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
26fe0 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
26ff0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
27000 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
27010 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
27020 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
27030 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
27040 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27050 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
27060 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
27070 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
27080 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
27090 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
270a0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
270b0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
270c0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
270d0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
270e0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
270f0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
27100 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
27110 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
27120 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
27130 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
27140 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
27150 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
27160 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
27170 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
27180 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
27190 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
271a0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
271b0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
271c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
271d0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
271e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
271f0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
27200 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
27210 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
27220 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
27230 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
27240 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
27250 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
27260 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
27270 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
27280 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
27290 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
272a0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
272b0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
272c0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
272d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
272e0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
272f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
27300 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
27310 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
27320 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
27330 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
27340 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
27350 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
27360 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
27370 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
27380 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
27390 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
273a0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
273b0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
273c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
273d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
273e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
273f0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
27400 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
27410 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
27420 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
27430 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
27440 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
27450 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
27460 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
27470 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
27480 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
27490 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
274a0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
274b0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
274c0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
274d0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
274e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
274f0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
27500 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
27510 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
27520 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
27530 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
27540 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
27550 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
27560 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
27570 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
27580 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
27590 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
275a0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
275b0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
275c0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
275d0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
275e0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
275f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
27600 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
27610 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
27620 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
27630 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
27640 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
27650 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
27660 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
27670 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
27680 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
27690 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
276a0 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
276b0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
276c0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
276d0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
276e0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
276f0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
27700 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
27710 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
27720 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
27730 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
27740 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
27750 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
27760 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
27770 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
27780 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
27790 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
277a0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
277b0 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
277c0 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
277d0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
277e0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
277f0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
27800 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
27810 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
27820 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
27830 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
27840 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
27850 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
27860 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
27870 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
27880 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
27890 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
278a0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
278b0 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
278c0 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
278d0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
278e0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
278f0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
27900 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
27910 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
27920 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
27930 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
27940 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
27950 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
27960 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
27970 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
27980 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
27990 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
279a0 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
279b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
279c0 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
279d0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
279e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
279f0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
27a00 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
27a10 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
27a20 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
27a30 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
27a40 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
27a50 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
27a60 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
27a70 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
27a80 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
27a90 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
27aa0 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
27ab0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
27ac0 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
27ad0 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
27ae0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
27af0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
27b00 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
27b10 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
27b20 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
27b30 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  bled..** </li>.*
27b40 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
27b50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
27b60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27b70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27b80 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27b90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
27ba0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27bb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27bc0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
27bd0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
27be0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
27bf0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
27c00 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
27c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
27c20 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
27c30 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
27c40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
27c50 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
27c60 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
27c70 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
27c80 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
27c90 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
27ca0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
27cb0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
27cc0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
27cd0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
27ce0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
27cf0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
27d00 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
27d10 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
27d20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
27d30 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
27d40 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
27d50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
27d60 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
27d70 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
27d80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27d90 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
27da0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
27db0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
27dc0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
27dd0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27de0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
27df0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
27e00 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
27e10 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27e20 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
27e30 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
27e40 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
27e50 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27e60 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27e70 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27e80 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27e90 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27ea0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27eb0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27ec0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27ed0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
27ee0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27ef0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
27f00 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27f10 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
27f20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27f30 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
27f40 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
27f50 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
27f60 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
27f70 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
27f80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
27f90 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
27fa0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
27fb0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
27fc0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27fd0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
27fe0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
27ff0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28000 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28010 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28020 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
28030 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
28040 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
28050 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
28060 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28070 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
28080 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
28090 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
280a0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
280b0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
280c0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
280d0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
280e0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
280f0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
28100 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
28110 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
28120 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
28130 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
28140 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28150 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
28160 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
28170 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28180 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
28190 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
281a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
281b0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
281c0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
281d0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
281e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
281f0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
28200 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
28210 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
28220 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
28230 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
28240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28250 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
28260 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
28270 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
28280 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
28290 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
282a0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
282b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
282c0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
282d0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
282e0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
282f0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
28300 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
28310 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
28320 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
28330 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
28340 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
28350 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
28360 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
28370 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
28380 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
28390 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
283a0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
283b0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
283c0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
283d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
283e0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
283f0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
28400 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
28410 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
28420 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
28430 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
28440 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
28450 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
28460 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
28470 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
28480 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
28490 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
284a0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
284b0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
284c0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
284d0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
284e0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
284f0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
28500 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
28510 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
28520 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
28530 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
28540 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
28550 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
28560 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
28570 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
28580 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
28590 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
285a0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
285b0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
285c0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
285d0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
285e0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
285f0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
28600 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
28610 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
28620 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
28630 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
28640 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
28650 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
28660 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
28670 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
28680 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
28690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
286a0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
286b0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
286c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
286d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
286e0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
286f0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
28700 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
28710 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
28720 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28730 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
28740 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28750 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
28760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28770 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
28780 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28790 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
287a0 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
287b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
287c0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
287d0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
287e0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
287f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
28800 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
28810 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
28820 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
28830 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
28840 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28850 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
28860 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
28870 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
28880 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
28890 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
288a0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
288b0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
288c0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
288d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
288e0 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
288f0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
28900 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
28910 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
28920 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
28930 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
28940 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
28950 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
28960 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
28970 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
28980 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
28990 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
289a0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
289b0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
289c0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
289d0 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
289e0 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
289f0 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
28a00 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
28a10 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
28a20 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
28a30 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
28a40 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
28a50 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
28a60 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
28a70 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
28a80 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28a90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
28aa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28ab0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
28ac0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
28ad0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
28ae0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28af0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
28b00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28b10 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
28b20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
28b30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
28b40 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
28b50 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
28b60 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
28b70 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
28b80 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
28b90 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
28ba0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
28bb0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
28bc0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
28bd0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28be0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
28bf0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
28c00 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
28c10 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
28c20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
28c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28c40 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
28c50 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
28c60 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
28c70 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
28c80 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
28c90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28ca0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
28cb0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
28cc0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
28cd0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
28ce0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
28cf0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
28d00 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
28d10 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
28d20 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
28d30 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
28d40 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
28d50 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
28d60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28d70 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
28d80 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
28d90 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
28da0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
28db0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
28dc0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
28dd0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
28de0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
28df0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
28e00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28e10 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
28e20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
28e30 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
28e40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28e50 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
28e60 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
28e70 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
28e80 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
28e90 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
28ea0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
28eb0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
28ec0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
28ed0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
28ee0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
28ef0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
28f00 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
28f10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
28f20 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
28f30 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
28f40 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
28f50 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
28f60 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
28f70 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
28f80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
28f90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
28fa0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
28fb0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
28fc0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
28fd0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
28fe0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
28ff0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
29000 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
29010 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
29020 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
29030 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
29040 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
29050 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
29060 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
29070 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
29080 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
29090 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
290a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
290b0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
290c0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
290d0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
290e0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
290f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29100 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
29110 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
29120 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
29130 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
29140 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
29150 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
29160 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
29170 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
29180 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29190 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
291a0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
291b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
291c0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
291d0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
291e0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
291f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
29200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
29210 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
29220 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
29230 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
29240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29250 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
29260 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
29270 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
29280 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
29290 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
292a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
292b0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
292c0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
292d0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
292e0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
292f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
29300 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
29310 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
29320 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
29330 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
29340 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
29350 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
29360 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
29370 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
29380 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29390 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
293a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
293b0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
293c0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
293d0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
293e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
293f0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
29400 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
29410 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
29420 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
29430 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
29440 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
29450 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
29460 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
29470 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
29480 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
29490 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
294a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
294b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
294c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
294d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
294e0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
294f0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
29500 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
29510 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
29520 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
29530 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
29540 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
29550 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
29560 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
29570 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
29580 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
29590 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
295a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
295b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
295c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
295d0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
295e0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
295f0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
29600 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
29610 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
29620 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
29630 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
29640 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
29650 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
29660 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
29670 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
29680 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
29690 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
296a0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
296b0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
296c0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
296d0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
296e0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
296f0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
29700 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
29710 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
29720 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
29730 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
29740 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
29750 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
29760 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
29770 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
29780 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
29790 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
297a0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
297b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
297c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
297d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
297e0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
297f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
29800 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
29810 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
29820 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
29830 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
29840 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
29850 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
29860 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
29870 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
29880 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
29890 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
298a0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
298b0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
298c0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
298d0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
298e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
298f0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
29900 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
29910 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
29920 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
29930 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
29940 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
29950 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
29960 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
29970 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
29980 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
29990 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
299a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
299b0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
299c0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
299d0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
299e0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
299f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
29a00 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
29a10 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
29a20 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
29a30 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
29a40 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
29a50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29a60 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
29a70 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
29a80 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
29a90 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
29aa0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
29ab0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
29ac0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
29ad0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29ae0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
29af0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
29b00 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
29b10 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
29b20 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
29b30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
29b40 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
29b50 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
29b60 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
29b70 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
29b80 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
29b90 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
29ba0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
29bb0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
29bc0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
29bd0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
29be0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
29bf0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
29c00 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
29c10 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
29c20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
29c30 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
29c40 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
29c50 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
29c60 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
29c70 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
29c80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29c90 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
29ca0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
29cb0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
29cc0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
29cd0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
29ce0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
29cf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
29d00 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
29d10 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
29d20 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
29d30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
29d40 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
29d50 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
29d60 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
29d70 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
29d80 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
29d90 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
29da0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
29db0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
29dc0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
29dd0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
29de0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
29df0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
29e00 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
29e10 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
29e20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
29e30 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
29e40 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
29e50 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
29e60 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
29e70 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
29e80 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
29e90 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
29ea0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
29eb0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
29ec0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
29ed0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
29ee0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
29ef0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
29f00 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
29f10 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
29f20 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
29f30 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
29f40 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
29f50 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
29f60 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
29f70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
29f80 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
29f90 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
29fa0 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
29fb0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
29fc0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
29fd0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
29fe0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
29ff0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2a000 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2a010 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2a020 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2a030 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2a040 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2a050 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2a060 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2a070 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2a080 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2a090 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2a0a0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2a0b0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2a0c0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2a0d0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2a0e0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2a0f0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2a100 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2a110 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2a120 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2a130 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2a140 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2a150 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2a160 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2a170 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2a180 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2a190 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2a1a0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2a1b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2a1c0 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2a1d0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2a1e0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2a1f0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2a200 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2a210 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2a220 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2a230 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2a240 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2a250 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2a260 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2a270 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2a280 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2a290 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2a2a0 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2a2b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2a2c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2a2d0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2a2e0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2a2f0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2a300 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2a310 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2a320 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2a330 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2a340 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2a350 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2a360 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2a370 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2a380 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a390 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2a3a0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2a3b0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2a3c0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2a3d0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2a3e0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2a3f0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2a400 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2a410 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2a420 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2a430 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2a440 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2a450 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2a460 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2a470 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2a480 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2a490 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2a4a0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2a4b0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2a4c0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2a4d0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2a4e0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2a4f0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2a500 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2a510 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2a520 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2a530 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2a540 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2a550 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2a560 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2a570 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2a580 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2a590 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a5a0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2a5b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2a5c0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2a5d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2a5e0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2a5f0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2a600 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a610 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2a620 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2a630 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2a640 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2a650 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2a660 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2a670 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a680 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2a690 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2a6a0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2a6b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2a6c0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2a6d0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2a6e0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2a6f0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2a700 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2a710 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2a720 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2a730 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2a740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a750 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2a760 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2a770 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2a780 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2a790 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2a7a0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2a7b0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2a7c0 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2a7d0 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2a7e0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2a7f0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2a800 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2a810 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2a820 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2a830 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2a840 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2a850 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2a860 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2a870 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2a880 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2a890 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2a8a0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2a8b0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2a8c0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2a8d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a8e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a8f0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2a900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a910 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a920 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2a930 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a940 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2a950 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2a960 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2a970 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2a980 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2a990 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2a9a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2a9b0 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2a9c0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2a9d0 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2a9e0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2a9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2aa00 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2aa10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2aa20 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2aa30 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2aa40 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
2aa50 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2aa60 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2aa70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2aa80 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2aa90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2aaa0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
2aab0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2aac0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2aad0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
2aae0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2aaf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ab00 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2ab10 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2ab20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2ab30 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2ab40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2ab50 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2ab60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2ab70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2ab80 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2ab90 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2aba0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2abb0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2abc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2abd0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2abe0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2abf0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20   encoding);.int 
2ac00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2ac10 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2ac20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2ac30 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2ac40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2ac50 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2ac60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2ac70 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
2ac80 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2ac90 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2aca0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2acb0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2acc0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2acd0 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2ace0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2acf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ad00 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2ad10 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2ad20 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2ad30 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2ad40 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2ad50 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2ad60 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2ad70 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2ad80 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2ad90 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2ada0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2adb0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2adc0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2add0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2ade0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2adf0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2ae00 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2ae10 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2ae20 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2ae30 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2ae40 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2ae50 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2ae60 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2ae70 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2ae80 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2ae90 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2aea0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2aeb0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2aec0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2aed0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2aee0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2aef0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2af00 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2af10 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2af20 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2af30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2af40 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2af50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2af60 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2af70 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2af80 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2af90 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2afa0 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
2afb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2afc0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2afd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2afe0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2aff0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2b000 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2b010 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b020 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2b030 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2b040 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2b050 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2b060 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2b070 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2b080 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2b090 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2b0a0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2b0b0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2b0c0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2b0d0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2b0e0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2b0f0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2b100 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2b110 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2b120 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2b130 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2b140 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2b150 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2b160 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2b170 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2b180 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2b190 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2b1a0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2b1b0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2b1c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2b1d0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2b1e0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2b1f0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2b200 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2b210 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2b220 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2b230 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2b240 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2b250 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2b260 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2b270 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2b280 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2b290 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2b2a0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2b2b0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2b2c0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2b2d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2b2e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b2f0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b300 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b310 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b320 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2b330 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b340 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b350 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2b360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b370 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b380 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2b390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b3a0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2b3b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2b3c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b3d0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2b3e0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2b3f0 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
2b400 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2b410 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2b420 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2b430 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2b440 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2b450 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2b460 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2b470 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2b480 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2b490 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2b4a0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2b4b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2b4c0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2b4d0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2b4e0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2b4f0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2b500 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2b510 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2b520 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2b530 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2b540 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2b550 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2b560 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2b570 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b580 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2b590 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2b5a0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2b5b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b5c0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2b5d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b5e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b5f0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2b600 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b610 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2b620 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2b630 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2b640 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2b650 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2b660 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2b670 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
2b680 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2b690 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2b6a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b6b0 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2b6c0 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2b6d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2b6e0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2b6f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b700 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2b710 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2b720 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2b730 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2b740 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
2b750 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2b760 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2b770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2b780 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2b790 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2b7a0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2b7b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2b7c0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2b7d0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
2b7e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2b7f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
2b800 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2b810 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
2b820 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
2b830 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
2b840 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
2b850 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
2b860 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
2b870 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b880 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
2b890 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2b8a0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2b8b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b8c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b8d0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2b8e0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2b8f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2b900 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2b910 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2b920 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2b930 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2b940 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2b950 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2b960 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2b970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2b980 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2b990 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2b9a0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2b9b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2b9c0 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2b9d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2b9e0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) 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 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2ba10 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2ba20 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2ba30 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2ba40 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2ba50 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2ba60 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2ba70 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2ba80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2ba90 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2baa0 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2bab0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2bac0 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2bad0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2bae0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2baf0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2bb00 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2bb10 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2bb20 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2bb30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2bb40 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2bb50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2bb60 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2bb70 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2bb80 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2bb90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2bba0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2bbb0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2bbc0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2bbd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2bbe0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2bbf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2bc00 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2bc10 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2bc20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2bc30 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2bc40 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2bc50 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2bc60 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2bc70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2bc80 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2bc90 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2bca0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2bcb0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2bcc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2bcd0 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2bce0 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2bcf0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2bd00 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2bd10 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2bd20 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2bd30 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2bd40 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2bd50 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2bd60 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2bd70 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2bd80 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2bd90 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2bda0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2bdb0 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
2bdc0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2bdd0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2bde0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
2bdf0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2be00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2be10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2be20 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2be30 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2be40 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2be50 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2be60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2be70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2be80 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2be90 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2bea0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2beb0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2bec0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2bed0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2bee0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2bef0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2bf00 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2bf10 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2bf20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2bf30 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2bf40 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2bf50 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2bf60 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2bf70 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2bf80 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2bf90 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2bfa0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2bfb0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2bfc0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2bfd0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2bfe0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2bff0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2c000 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2c010 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2c020 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2c030 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2c040 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2c050 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2c060 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2c070 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2c080 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2c090 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2c0a0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2c0b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2c0c0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2c0d0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2c0e0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2c0f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2c100 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2c110 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2c120 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2c130 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2c140 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2c150 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2c160 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2c170 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2c180 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2c190 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2c1a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2c1b0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2c1c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c1d0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2c1e0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2c1f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2c200 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2c210 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2c220 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2c230 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2c240 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2c250 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2c260 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2c270 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2c280 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2c290 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2c2a0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2c2b0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2c2c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c2d0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2c2e0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2c2f0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2c300 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2c310 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2c320 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2c330 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2c340 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2c350 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2c360 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2c370 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2c380 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2c390 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2c3a0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2c3b0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2c3c0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2c3d0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2c3e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2c3f0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2c400 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2c410 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2c420 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2c430 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2c440 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2c450 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2c460 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2c470 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2c480 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2c490 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2c4a0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2c4b0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2c4c0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2c4d0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2c4e0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2c4f0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2c500 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2c510 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2c520 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2c530 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2c540 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2c550 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2c560 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2c570 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2c580 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2c590 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2c5a0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2c5b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2c5c0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2c5d0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2c5e0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2c5f0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2c600 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2c610 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2c620 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2c630 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2c640 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2c650 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2c660 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2c670 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2c680 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2c690 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2c6a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2c6b0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2c6c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2c6d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c6e0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2c6f0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2c700 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2c710 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2c720 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2c730 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2c740 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2c750 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c760 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2c770 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c780 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2c790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2c7a0 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
2c7b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2c7c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c7d0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2c7e0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2c7f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2c800 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2c810 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2c820 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2c830 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2c840 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2c850 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c860 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2c870 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2c880 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2c890 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2c8a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2c8b0 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2c8c0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2c8d0 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2c8e0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2c8f0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2c900 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2c910 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2c920 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2c930 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2c940 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2c950 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2c960 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2c970 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2c980 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2c990 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2c9a0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2c9b0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2c9c0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2c9d0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2c9e0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2c9f0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2ca00 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2ca10 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2ca20 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2ca30 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2ca40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2ca50 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2ca60 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2ca70 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2ca80 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2ca90 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2caa0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2cab0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2cac0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2cad0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2cae0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2caf0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2cb00 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2cb10 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2cb20 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2cb30 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2cb40 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2cb50 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2cb60 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2cb70 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2cb80 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2cb90 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2cba0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2cbb0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2cbc0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2cbd0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2cbe0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2cbf0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2cc00 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2cc10 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2cc20 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2cc30 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2cc40 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2cc50 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2cc60 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2cc70 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2cc80 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
2cc90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2cca0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2ccb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ccc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ccd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2cce0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2ccf0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2cd00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2cd10 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2cd20 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2cd30 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2cd40 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2cd50 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2cd60 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2cd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2cd80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2cd90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2cda0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2cdb0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2cdc0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2cdd0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2cde0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2cdf0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2ce00 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2ce10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2ce20 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2ce30 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2ce40 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2ce50 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2ce60 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2ce70 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2ce80 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2ce90 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2cea0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2ceb0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2cec0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2ced0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2cee0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2cef0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2cf00 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2cf10 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2cf20 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2cf30 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2cf40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cf50 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2cf60 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2cf70 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2cf80 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2cf90 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2cfa0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2cfb0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2cfc0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2cfd0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2cfe0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2cff0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2d000 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2d010 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2d020 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2d030 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2d040 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2d050 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2d060 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2d070 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2d080 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2d090 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2d0a0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2d0b0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2d0c0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2d0d0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2d0e0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2d0f0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2d100 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2d110 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2d120 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2d130 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2d140 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2d150 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2d160 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2d170 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2d180 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2d190 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2d1a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2d1b0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2d1c0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2d1d0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2d1e0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2d1f0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2d200 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2d210 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2d220 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2d230 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2d240 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2d250 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2d260 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2d270 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2d280 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2d290 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2d2a0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2d2b0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2d2c0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2d2d0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2d2e0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2d2f0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2d300 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2d310 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2d320 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2d330 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2d340 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2d350 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2d360 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2d370 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2d380 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2d390 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2d3a0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2d3b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2d3c0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2d3d0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2d3e0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2d3f0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2d400 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2d410 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2d420 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2d430 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2d440 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2d450 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2d460 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2d470 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2d480 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2d490 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2d4a0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2d4b0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2d4c0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2d4d0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2d4e0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2d4f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2d500 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2d510 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2d520 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2d530 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2d540 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2d550 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2d560 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2d570 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2d580 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2d590 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2d5a0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2d5b0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2d5c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2d5d0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2d5e0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2d5f0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2d600 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2d610 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2d620 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2d630 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d640 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2d650 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2d660 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2d670 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2d680 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2d690 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2d6a0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2d6b0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2d6c0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2d6d0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2d6e0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2d6f0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2d700 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2d710 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d720 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2d730 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2d740 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d750 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2d760 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2d770 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2d780 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2d790 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2d7a0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2d7b0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2d7c0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2d7d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2d7e0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2d7f0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2d800 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2d810 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2d820 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2d830 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2d840 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2d850 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2d860 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2d870 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d880 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2d890 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2d8a0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2d8b0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2d8c0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2d8d0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2d8e0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2d8f0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2d900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2d910 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2d920 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d930 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2d940 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2d950 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2d960 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2d970 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2d980 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2d990 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2d9a0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2d9b0 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2d9c0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2d9d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2d9e0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2d9f0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2da00 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2da10 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2da20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2da30 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2da40 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2da50 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2da60 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2da70 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2da80 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2da90 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2daa0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2dab0 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2dac0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2dad0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2dae0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2daf0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2db00 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2db10 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2db20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2db30 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2db40 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2db50 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2db60 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2db70 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2db80 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2db90 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2dba0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2dbb0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2dbc0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2dbd0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2dbe0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2dbf0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2dc00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2dc10 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2dc20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2dc30 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2dc40 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2dc50 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2dc60 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2dc70 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2dc80 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2dc90 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2dca0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2dcb0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2dcc0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2dcd0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2dce0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2dcf0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2dd00 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2dd10 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2dd20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dd30 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2dd40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2dd50 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2dd60 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2dd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2dd80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2dd90 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2dda0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2ddb0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2ddc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2ddd0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2dde0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2ddf0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2de00 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2de10 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2de20 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
2de30 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2de40 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2de50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2de60 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2de70 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2de80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2de90 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2dea0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2deb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2dec0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2ded0 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2dee0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2def0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2df00 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2df10 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2df20 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2df30 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2df40 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2df50 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2df60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2df70 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2df80 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2df90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2dfa0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2dfb0 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2dfc0 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2dfd0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2dfe0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2dff0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2e000 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2e010 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2e020 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2e030 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2e040 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2e050 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2e060 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2e070 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2e080 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2e090 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2e0a0 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2e0b0 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2e0c0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2e0d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2e0e0 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2e0f0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2e100 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2e110 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2e120 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2e130 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2e140 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2e150 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2e160 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2e170 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2e180 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2e190 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2e1a0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2e1b0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2e1c0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
2e1d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
2e1e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2e1f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e200 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
2e210 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
2e220 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
2e230 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
2e240 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
2e250 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
2e260 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
2e270 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
2e280 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
2e290 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2e2a0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2e2b0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
2e2c0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
2e2d0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
2e2e0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
2e2f0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
2e300 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2e310 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
2e320 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
2e330 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
2e340 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
2e350 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
2e360 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
2e370 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
2e380 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
2e390 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
2e3a0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
2e3b0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
2e3c0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
2e3d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
2e3e0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
2e3f0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
2e400 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
2e410 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
2e420 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2e430 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
2e440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
2e450 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
2e460 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
2e470 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2e480 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
2e490 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2e4a0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
2e4b0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
2e4c0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
2e4d0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
2e4e0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
2e4f0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
2e500 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
2e510 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
2e520 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
2e530 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
2e540 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2e550 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
2e560 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
2e570 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
2e580 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2e590 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2e5a0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2e5b0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2e5c0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2e5d0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2e5e0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2e5f0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2e600 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2e610 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2e620 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2e630 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2e640 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2e650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2e660 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2e670 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2e680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2e690 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2e6a0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2e6b0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2e6c0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2e6d0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2e6e0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2e6f0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2e700 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2e710 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2e720 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2e730 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2e740 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2e750 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2e760 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2e770 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2e780 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2e790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2e7a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2e7b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e7c0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2e7d0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2e7e0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2e7f0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2e800 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2e810 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2e820 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2e830 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2e840 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2e850 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2e860 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2e870 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2e880 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2e890 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2e8a0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2e8b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2e8c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2e8d0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2e8e0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2e8f0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2e900 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2e910 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2e920 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2e930 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2e940 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e950 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2e960 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2e970 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2e980 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2e990 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2e9a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2e9b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2e9c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2e9d0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2e9e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e9f0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2ea00 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2ea10 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2ea20 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
2ea30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2ea40 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
2ea50 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2ea60 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2ea70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ea80 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2ea90 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2eaa0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2eab0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2eac0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2ead0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2eae0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2eaf0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
2eb00 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
2eb10 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2eb20 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
2eb30 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2eb40 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
2eb50 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
2eb60 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
2eb70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
2eb80 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2eb90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2eba0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
2ebb0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
2ebc0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
2ebd0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
2ebe0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
2ebf0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
2ec00 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
2ec10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
2ec20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ec30 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
2ec40 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
2ec50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2ec60 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
2ec70 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2ec80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2ec90 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
2eca0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2ecb0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
2ecc0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2ecd0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2ece0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2ecf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ed00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2ed10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2ed20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2ed30 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2ed40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2ed50 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2ed60 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2ed70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ed80 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2ed90 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2eda0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2edb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2edc0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2edd0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ede0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2edf0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2ee00 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
2ee10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2ee20 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2ee30 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2ee40 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
2ee50 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2ee60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2ee70 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2ee80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2ee90 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2eea0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2eeb0 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
2eec0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
2eed0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2eee0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
2eef0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2ef00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ef10 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
2ef20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2ef30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ef40 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2ef50 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2ef60 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2ef70 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
2ef80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ef90 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
2efa0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2efb0 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
2efc0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2efd0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2efe0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2eff0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2f000 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2f010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f020 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
2f030 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2f040 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2f050 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2f060 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
2f070 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2f080 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2f090 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2f0a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2f0b0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2f0c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f0d0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
2f0e0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
2f0f0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2f100 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2f110 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2f120 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2f130 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
2f140 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
2f150 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2f160 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
2f170 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
2f180 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
2f190 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2f1a0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2f1b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f1c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2f1d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2f1e0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
2f1f0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
2f200 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
2f210 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2f220 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
2f230 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
2f240 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2f250 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
2f260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f270 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
2f280 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
2f290 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
2f2a0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
2f2b0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
2f2c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
2f2d0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
2f2e0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2f2f0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
2f300 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2f310 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2f320 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2f330 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
2f340 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2f350 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f360 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
2f370 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f380 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
2f390 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2f3a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2f3b0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
2f3c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2f3d0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
2f3e0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
2f3f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2f400 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2f410 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2f420 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2f430 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
2f440 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
2f450 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
2f460 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2f470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2f480 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
2f490 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2f4a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2f4b0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
2f4c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2f4d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2f4e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2f4f0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
2f500 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
2f510 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
2f520 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
2f530 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
2f540 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
2f550 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
2f560 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
2f570 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
2f580 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2f590 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
2f5a0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
2f5b0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
2f5c0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
2f5d0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
2f5e0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
2f5f0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
2f600 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
2f610 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
2f620 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2f630 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2f640 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
2f650 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
2f660 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
2f670 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
2f680 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
2f690 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2f6a0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2f6b0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
2f6c0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2f6d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2f6e0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2f6f0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
2f700 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2f710 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
2f720 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
2f730 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
2f740 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2f750 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
2f760 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
2f770 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2f780 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2f790 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2f7a0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
2f7b0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
2f7c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2f7d0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
2f7e0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2f7f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
2f800 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2f810 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2f820 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2f830 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
2f840 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2f850 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2f860 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2f870 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2f880 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2f890 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2f8a0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2f8b0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2f8c0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2f8d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2f8e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2f8f0 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
2f900 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2f910 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2f920 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f930 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2f940 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2f950 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2f960 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
2f970 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
2f980 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2f990 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2f9a0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2f9b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2f9c0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
2f9d0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
2f9e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2f9f0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
2fa00 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2fa10 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
2fa20 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2fa30 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2fa40 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2fa50 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2fa60 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2fa70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2fa80 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2fa90 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2faa0 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2fab0 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2fac0 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2fad0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2fae0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2faf0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2fb00 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2fb10 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2fb20 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2fb30 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2fb40 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2fb50 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2fb60 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2fb70 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2fb80 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2fb90 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2fba0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2fbb0 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2fbc0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2fbd0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2fbe0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2fbf0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2fc00 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2fc10 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2fc20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fc30 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2fc40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fc50 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2fc60 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2fc70 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2fc80 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2fc90 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2fca0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2fcb0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2fcc0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2fcd0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2fce0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2fcf0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2fd00 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2fd10 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2fd20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2fd30 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2fd40 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2fd50 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2fd60 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2fd70 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2fd80 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2fd90 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2fda0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2fdb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2fdc0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2fdd0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2fde0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2fdf0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2fe00 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2fe10 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2fe20 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2fe30 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2fe40 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2fe50 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2fe60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2fe70 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2fe80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fe90 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2fea0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2feb0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2fec0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2fed0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2fee0 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2fef0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2ff00 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2ff10 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2ff20 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2ff30 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2ff40 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2ff50 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2ff60 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2ff70 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2ff80 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2ff90 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2ffa0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2ffb0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2ffc0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2ffd0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2ffe0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2fff0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
30000 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
30010 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
30020 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
30030 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
30040 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
30050 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
30060 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
30070 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
30080 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
30090 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
300a0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
300b0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
300c0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
300d0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
300e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
300f0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
30100 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
30110 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
30120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30130 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
30140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30150 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
30160 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
30170 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
30180 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
30190 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
301a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
301b0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
301c0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
301d0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
301e0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
301f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30200 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
30210 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
30220 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
30230 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
30240 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
30250 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
30260 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
30270 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
30280 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30290 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
302a0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
302b0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
302c0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
302d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
302e0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
302f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
30300 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
30310 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
30320 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
30330 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
30340 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30350 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
30360 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
30370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30380 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
30390 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
303a0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
303b0 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
303c0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
303d0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
303e0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
303f0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
30400 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30410 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
30420 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
30430 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
30440 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
30450 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
30460 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
30470 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
30480 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
30490 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
304a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
304b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
304c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
304d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
304e0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
304f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
30500 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
30510 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
30520 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
30530 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
30540 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
30550 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
30560 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
30570 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
30580 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
30590 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
305a0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
305b0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
305c0 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
305d0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
305e0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
305f0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
30600 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
30610 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
30620 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
30630 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
30640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30650 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
30660 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
30670 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
30680 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
30690 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
306a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
306b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
306c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
306d0 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
306e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
306f0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
30700 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
30710 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30720 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
30730 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
30740 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
30750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
30760 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30770 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
30780 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
30790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
307a0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
307b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
307c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
307d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
307e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
307f0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
30800 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
30810 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30820 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
30830 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
30840 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
30850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30860 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
30870 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
30880 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
30890 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
308a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
308b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
308c0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
308d0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
308e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
308f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
30900 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
30910 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
30920 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
30930 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
30940 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
30950 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
30960 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
30970 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30980 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
30990 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
309a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
309b0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
309c0 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
309d0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
309e0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
309f0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
30a00 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
30a10 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
30a20 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
30a30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30a40 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
30a50 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
30a60 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
30a70 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
30a80 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
30a90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30aa0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
30ab0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
30ac0 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
30ad0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
30ae0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
30af0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
30b00 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
30b10 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
30b20 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
30b30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
30b40 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
30b50 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
30b60 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
30b70 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
30b80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30b90 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
30ba0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
30bb0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
30bc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
30bd0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
30be0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
30bf0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
30c00 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
30c10 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
30c20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
30c30 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
30c40 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
30c50 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
30c60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
30c70 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
30c80 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
30c90 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
30ca0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
30cb0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
30cc0 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
30cd0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
30ce0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
30cf0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
30d00 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
30d10 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
30d20 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
30d30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
30d40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
30d50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30d60 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
30d70 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
30d80 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
30d90 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
30da0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
30db0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
30dc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30dd0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
30de0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
30df0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
30e00 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
30e10 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
30e20 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
30e30 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
30e40 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
30e50 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
30e60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
30e70 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
30e80 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
30e90 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
30ea0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
30eb0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
30ec0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
30ed0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
30ee0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30ef0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
30f00 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
30f10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
30f20 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
30f30 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
30f40 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
30f50 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
30f60 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
30f70 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
30f80 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
30f90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
30fa0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
30fb0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
30fc0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
30fd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30fe0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
30ff0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
31000 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
31010 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
31020 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
31030 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
31040 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
31050 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
31060 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
31070 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
31080 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
31090 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
310a0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
310b0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
310c0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
310d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
310e0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
310f0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
31100 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
31110 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
31120 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
31130 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
31140 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
31150 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31160 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
31170 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
31180 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
31190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
311a0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
311b0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
311c0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
311d0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
311e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
311f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
31200 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31210 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
31220 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
31230 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31240 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
31250 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
31260 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
31270 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
31280 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
31290 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
312a0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
312b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
312c0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
312d0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
312e0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
312f0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
31300 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
31310 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
31320 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
31330 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
31340 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
31350 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
31360 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
31370 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
31380 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
31390 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
313a0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
313b0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
313c0 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
313d0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
313e0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
313f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
31400 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
31410 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
31420 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
31430 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
31440 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
31450 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
31460 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
31470 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
31480 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
31490 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
314a0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
314b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
314c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
314d0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
314e0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
314f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
31500 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
31510 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
31520 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
31530 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
31540 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
31550 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
31560 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
31570 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
31580 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
31590 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
315a0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
315b0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
315c0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
315d0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
315e0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
315f0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
31600 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
31610 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
31620 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
31630 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
31640 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
31650 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
31660 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
31670 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
31680 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
31690 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
316a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
316b0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
316c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
316d0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
316e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
316f0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
31700 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
31710 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
31720 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
31730 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
31740 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
31750 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
31760 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
31770 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
31780 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
31790 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
317a0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
317b0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
317c0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
317d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
317e0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
317f0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
31800 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
31810 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
31820 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
31830 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
31840 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
31850 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
31860 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
31870 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
31880 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
31890 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
318a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
318b0 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
318c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
318d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
318e0 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
318f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
31900 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
31910 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31920 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
31930 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
31940 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
31950 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
31960 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
31970 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
31980 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
31990 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
319a0 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
319b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
319c0 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
319d0 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
319e0 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
319f0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
31a00 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
31a10 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
31a20 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
31a30 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
31a40 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
31a50 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
31a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
31a70 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
31a80 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
31a90 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
31aa0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
31ab0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
31ac0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
31ad0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
31ae0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
31af0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
31b00 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
31b10 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
31b20 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
31b30 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
31b40 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
31b50 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
31b60 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
31b70 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
31b80 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
31b90 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
31ba0 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
31bb0 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
31bc0 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
31bd0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
31be0 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
31bf0 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
31c00 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
31c10 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
31c20 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
31c30 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
31c40 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
31c50 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
31c60 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
31c70 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
31c80 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
31c90 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
31ca0 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
31cb0 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
31cc0 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
31cd0 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
31ce0 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
31cf0 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
31d00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
31d10 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
31d20 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
31d30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
31d40 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
31d50 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
31d60 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
31d70 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
31d80 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
31d90 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
31da0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
31db0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
31dc0 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
31dd0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
31de0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
31df0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
31e00 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
31e10 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
31e20 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
31e30 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
31e40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
31e50 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
31e60 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
31e70 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
31e80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31e90 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
31ea0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
31eb0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
31ec0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
31ed0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
31ee0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
31ef0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
31f00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
31f10 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
31f20 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
31f30 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
31f40 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
31f50 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
31f60 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
31f70 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
31f80 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
31f90 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
31fa0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
31fb0 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
31fc0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
31fd0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
31fe0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
31ff0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
32000 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32010 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
32020 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
32030 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
32040 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32050 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
32060 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
32070 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
32080 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
32090 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
320a0 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
320b0 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
320c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
320d0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
320e0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
320f0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
32100 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
32110 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
32120 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
32130 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
32140 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
32150 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
32160 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
32170 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
32180 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
32190 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
321a0 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
321b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
321c0 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
321d0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
321e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
321f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
32200 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
32210 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
32220 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
32230 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
32240 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32250 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
32260 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
32270 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
32280 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
32290 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
322a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
322b0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
322c0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
322d0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
322e0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
322f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
32300 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
32310 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
32320 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
32330 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
32340 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
32350 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
32360 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
32370 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
32380 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
32390 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
323a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
323b0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
323c0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
323d0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
323e0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
323f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
32400 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
32410 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
32420 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
32430 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
32440 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
32450 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
32460 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
32470 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
32480 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
32490 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
324a0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
324b0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
324c0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
324d0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
324e0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
324f0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
32500 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
32510 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
32520 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
32530 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
32540 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
32550 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32560 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
32570 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
32580 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
32590 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
325a0 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
325b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
325c0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
325d0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
325e0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
325f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
32600 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
32610 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
32620 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
32630 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
32640 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
32650 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32660 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
32670 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
32680 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
32690 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
326a0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
326b0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
326c0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
326d0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
326e0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
326f0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32700 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
32710 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
32720 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
32730 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
32740 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
32750 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
32760 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32770 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
32780 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
32790 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
327a0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
327b0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
327c0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
327d0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
327e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
327f0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32800 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32810 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
32820 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32830 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32840 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
32850 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32860 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
32870 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32880 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
32890 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
328a0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
328b0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
328c0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
328d0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
328e0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
328f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32900 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32910 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
32920 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32930 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32940 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32950 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
32960 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
32970 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
32980 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
32990 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
329a0 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
329b0 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
329c0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
329d0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
329e0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
329f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
32a00 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
32a10 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
32a20 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
32a30 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50       1    /* IMP
32a40 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20  : R-37514-35566 
32a50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32a60 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
32a70 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   2    /* IMP: R-
32a80 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23  03371-37637 */.#
32a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32aa0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20  F16BE        3  
32ab0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37    /* IMP: R-5197
32ac0 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69  1-34154 */.#defi
32ad0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
32ae0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
32af0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
32b00 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
32b10 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
32b20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
32b30 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64  Deprecated */.#d
32b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
32b50 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
32b60 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
32b70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
32b80 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
32b90 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46  3REF: Function F
32ba0 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
32bb0 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
32bc0 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20  e ORed together 
32bd0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
32be0 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66  LITE_UTF8 | pref
32bf0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
32c00 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72  ing] as the four
32c10 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
32c20 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
32c30 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b  e_function()], [
32c40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32c50 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  unction16()], or
32c60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
32c70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
32c80 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
32c90 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
32ca0 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a  TIC    0x800../*
32cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
32cc0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
32cd0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
32ce0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
32cf0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
32d00 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
32d10 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
32d20 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
32d30 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
32d40 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
32d50 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
32d60 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
32d70 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
32d80 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
32d90 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
32da0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
32db0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
32dc0 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72   To encourage pr
32dd0 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f  ogrammers to avo
32de0 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63  id.** these func
32df0 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e  tions, we will n
32e00 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20  ot explain what 
32e10 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
32e20 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
32e30 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
32e40 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
32e50 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32e60 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
32e70 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
32e80 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32e90 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
32ea0 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
32eb0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
32ec0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
32ed0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
32ee0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
32ef0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
32f00 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32f10 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
32f20 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
32f30 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
32f40 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
32f50 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
32f60 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
32f70 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32f80 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
32f90 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
32fa0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
32fb0 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20  ,int),.         
32fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
32fd0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
32fe0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
32ff0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
33000 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
33010 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
33020 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
33030 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
33040 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
33050 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
33060 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
33070 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
33080 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
33090 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
330a0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
330b0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
330c0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
330d0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
330e0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
330f0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
33100 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
33110 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
33120 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33130 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
33140 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33150 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
33160 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
33170 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
33180 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
33190 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
331a0 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
331b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
331c0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
331d0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
331e0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
331f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33200 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
33210 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
33220 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33230 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
33240 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
33250 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
33260 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
33270 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
33280 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
33290 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
332a0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
332b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
332c0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
332d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
332e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
332f0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
33300 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
33310 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
33320 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
33330 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
33340 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
33350 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
33360 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
33370 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
33380 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
33390 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
333a0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
333b0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
333c0 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  at these routine
333d0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
333e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
333f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
33400 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
33410 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
33420 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
33430 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
33440 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
33450 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33460 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
33470 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
33480 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
33490 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
334a0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
334b0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
334c0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
334d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
334e0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
334f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
33500 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
33510 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
33520 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
33530 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
33540 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
33550 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
33560 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
33570 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
33580 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
33590 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
335a0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
335b0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
335c0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
335d0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
335e0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
335f0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
33600 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
33610 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
33620 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
33630 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
33640 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
33650 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
33660 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
33670 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
33680 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
33690 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
336a0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
336b0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
336c0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
336d0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
336e0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
336f0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
33700 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
33710 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
33720 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
33730 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
33740 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
33750 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
33760 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
33770 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
33780 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
33790 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
337a0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
337b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
337c0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
337d0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
337e0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
337f0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
33800 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
33810 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
33820 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
33830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33840 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
33850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33860 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
33870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
33880 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
33890 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
338a0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
338b0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
338c0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
338d0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
338e0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
338f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
33900 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
33910 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
33920 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
33930 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
33940 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
33950 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
33960 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
33970 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
33980 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
33990 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
339a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
339b0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
339c0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
339d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
339e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
339f0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
33a00 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
33a10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
33a20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
33a30 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33a40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
33a50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33a60 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
33a70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33a80 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
33a90 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
33aa0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
33ab0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
33ac0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
33ad0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
33ae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33af0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
33b00 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
33b10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33b20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33b30 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
33b40 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
33b50 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
33b60 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
33b70 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
33b80 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
33b90 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
33ba0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
33bb0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
33bc0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
33bd0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
33be0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33bf0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
33c00 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
33c10 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
33c20 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
33c30 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
33c40 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
33c50 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
33c60 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
33c70 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
33c80 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
33c90 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
33ca0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
33cb0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
33cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
33cd0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33ce0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
33cf0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
33d00 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
33d10 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
33d20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
33d30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33d40 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
33d50 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
33d60 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
33d70 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
33d80 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
33d90 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
33da0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
33db0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
33dc0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
33dd0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
33de0 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
33df0 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
33e00 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
33e10 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
33e20 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
33e30 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
33e40 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
33e50 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
33e60 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
33e70 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
33e80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33e90 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
33ea0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
33eb0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
33ec0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
33ed0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
33ee0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
33ef0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33f00 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
33f10 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
33f20 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
33f30 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
33f40 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
33f50 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
33f60 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
33f70 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
33f80 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
33f90 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
33fa0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
33fb0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33fc0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
33fd0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
33fe0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
33ff0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
34000 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
34010 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
34020 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
34030 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
34040 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
34050 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
34060 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
34070 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
34080 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
34090 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
340a0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
340b0 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
340c0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
340d0 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
340e0 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
340f0 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
34100 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34110 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
34120 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
34130 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
34140 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
34150 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
34160 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
34170 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
34180 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
34190 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
341a0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
341b0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
341c0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
341d0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
341e0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
341f0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
34200 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
34210 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
34220 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
34230 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
34240 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
34250 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
34260 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
34270 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
34280 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
34290 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
342a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
342b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
342c0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
342d0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
342e0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
342f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
34300 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
34310 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34320 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
34330 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
34340 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
34350 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
34360 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
34370 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34380 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
34390 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
343a0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
343b0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
343c0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
343d0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
343e0 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
343f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
34400 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34410 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
34420 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34430 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
34440 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
34450 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
34460 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
34470 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34480 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
34490 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
344a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
344b0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
344c0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
344d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
344e0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
344f0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
34500 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
34510 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
34520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34530 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
34540 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
34550 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
34560 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
34570 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
34580 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
34590 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
345a0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
345b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
345c0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
345d0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
345e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
345f0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
34600 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
34610 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
34620 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
34630 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
34640 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
34650 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
34660 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
34670 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
34680 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
34690 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
346a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
346b0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
346c0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
346d0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
346e0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
346f0 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
34700 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
34710 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
34720 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
34730 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
34740 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
34750 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
34760 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
34770 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
34780 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
34790 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
347a0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
347b0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
347c0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
347d0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
347e0 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
347f0 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
34800 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
34810 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
34820 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
34830 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
34840 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
34850 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
34860 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
34870 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
34880 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
34890 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
348a0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
348b0 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
348c0 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
348d0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
348e0 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
348f0 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
34900 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
34910 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
34920 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
34930 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
34940 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
34950 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
34960 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
34970 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
34980 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34990 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
349a0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
349b0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
349c0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
349d0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
349e0 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
349f0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
34a00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34a10 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
34a20 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
34a30 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
34a40 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
34a50 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
34a60 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
34a70 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
34a80 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
34a90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
34aa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34ab0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
34ac0 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
34ad0 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
34ae0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
34af0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
34b00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34b10 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34b20 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
34b30 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
34b40 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
34b50 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
34b60 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
34b70 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
34b80 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
34b90 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
34ba0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
34bb0 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
34bc0 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
34bd0 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
34be0 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
34bf0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
34c00 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34c10 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
34c20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
34c30 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
34c40 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
34c50 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
34c60 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
34c70 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
34c80 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
34c90 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
34ca0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
34cb0 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
34cc0 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
34cd0 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
34ce0 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77  : <ul>.** <li> w
34cf0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
34d00 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
34d10 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
34d20 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
34d30 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
34d40 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
34d50 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
34d60 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
34d70 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
34d80 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ent, or.** <li> 
34d90 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74  when sqlite3_set
34da0 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e  _auxdata() is in
34db0 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  voked again on t
34dc0 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
34dd0 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75  r, or.** <li> du
34de0 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
34df0 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
34e00 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
34e10 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
34e20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
34e30 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75  rror occurs. </u
34e40 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  l>)^.**.** Note 
34e50 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
34e60 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
34e70 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
34e80 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
34e90 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
34ea0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
34eb0 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
34ec0 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
34ed0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34ee0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
34ef0 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
34f00 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
34f10 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
34f20 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
34f30 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
34f40 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
34f50 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
34f60 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
34f70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
34f80 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
34f90 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
34fa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
34fb0 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
34fc0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
34fd0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
34fe0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
34ff0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
35000 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
35010 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
35020 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
35030 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
35040 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
35050 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
35060 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
35070 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
35080 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
35090 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
350a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
350b0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
350c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
350d0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
350e0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
350f0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
35100 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
35110 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
35120 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35130 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
35140 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
35150 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
35160 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
35170 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
35180 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
35190 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
351a0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
351b0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
351c0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
351d0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
351e0 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
351f0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
35200 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
35210 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
35220 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
35230 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
35240 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
35250 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
35260 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
35270 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
35280 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
35290 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
352a0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
352b0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
352c0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
352d0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
352e0 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
352f0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
35300 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
35310 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
35320 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
35330 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
35340 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
35350 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
35360 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
35370 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
35380 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
35390 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
353a0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
353b0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
353c0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
353d0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
353e0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
353f0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
35400 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
35410 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
35420 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
35430 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
35440 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
35450 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
35460 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
35470 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
35480 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
35490 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
354a0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
354b0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
354c0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
354d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
354e0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
354f0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
35500 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
35510 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
35520 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
35530 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
35540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
35550 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
35560 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
35570 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
35580 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
35590 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
355a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
355b0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
355c0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
355d0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
355e0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
355f0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
35600 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
35610 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
35620 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
35630 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
35640 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
35650 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
35660 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
35670 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
35680 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
35690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
356a0 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
356b0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
356c0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
356d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
356e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
356f0 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
35700 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
35710 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
35720 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
35730 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
35740 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
35750 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
35760 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
35770 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35780 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
35790 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
357a0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
357b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
357c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
357d0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
357e0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
357f0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
35800 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
35810 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
35820 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
35830 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
35840 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35850 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
35860 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35870 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
35880 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35890 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
358a0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
358b0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
358c0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
358d0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
358e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
358f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
35900 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
35910 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
35920 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
35930 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
35940 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
35950 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
35960 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
35970 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
35980 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
35990 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
359a0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
359b0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
359c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
359d0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
359e0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
359f0 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
35a00 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
35a10 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
35a20 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
35a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35a40 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
35a50 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
35a60 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
35a70 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
35a80 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
35a90 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
35aa0 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
35ab0 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
35ac0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
35ad0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35ae0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
35af0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35b00 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
35b10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
35b20 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
35b30 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
35b40 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
35b50 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
35b60 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
35b70 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
35b80 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
35b90 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
35ba0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
35bb0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
35bc0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
35bd0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
35be0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
35bf0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
35c00 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
35c10 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
35c20 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
35c30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35c40 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
35c50 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
35c60 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
35c70 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
35c80 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
35c90 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
35ca0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
35cb0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
35cc0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
35cd0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
35ce0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
35cf0 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
35d00 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
35d10 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
35d20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35d30 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
35d40 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
35d50 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
35d60 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
35d70 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
35d80 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
35d90 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
35da0 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
35db0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
35dc0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
35dd0 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
35de0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
35df0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
35e00 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
35e10 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
35e20 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
35e30 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
35e40 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
35e50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35e60 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
35e70 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
35e80 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
35e90 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
35ea0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
35eb0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
35ec0 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
35ed0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
35ee0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35ef0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
35f00 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
35f10 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
35f20 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
35f30 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
35f40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
35f50 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
35f60 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35f70 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
35f80 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
35f90 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
35fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35fb0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35fc0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
35fd0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
35fe0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
35ff0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
36000 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
36010 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
36020 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
36030 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
36040 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
36050 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36060 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
36070 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
36080 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
36090 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
360a0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
360b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
360c0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
360d0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
360e0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
360f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
36100 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36110 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
36120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36130 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
36140 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
36150 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
36160 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36170 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
36180 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36190 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
361a0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
361b0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
361c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
361d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
361e0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
361f0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
36200 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
36210 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
36220 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
36230 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
36240 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
36250 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
36260 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54  pectively..** ^T
36270 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36280 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65 72  t_text64() inter
36290 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
362a0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
362b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  .** application-
362c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
362d0 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73 74   to be a text st
362e0 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64  ring in an encod
362f0 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64  ing.** specified
36300 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28 61   by the fifth (a
36310 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74  nd last) paramet
36320 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62  er, which must b
36330 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c  e one.** of [SQL
36340 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
36350 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
36360 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
36370 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
36380 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b  ..** ^SQLite tak
36390 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
363a0 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
363b0 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
363c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
363d0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
363e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
363f0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66  terfaces..** ^If
36400 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
36410 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
36420 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
36430 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
36440 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
36450 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
36460 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
36470 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
36480 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
36490 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
364a0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  er..** ^If the 3
364b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
364c0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
364d0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
364e0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
364f0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
36500 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
36510 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
36520 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
36530 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
36540 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
36550 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
36560 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
36570 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
36580 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20  lt.  If the 3rd 
36590 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
365a0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
365b0 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68  it.** must be th
365c0 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e  e byte offset in
365d0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  to the string wh
365e0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
365f0 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20  inator would.** 
36600 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74  appear if the st
36610 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74  ring where NUL t
36620 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
36630 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
36640 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  s occur.** in th
36650 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79  e string at a by
36660 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69  te offset that i
36670 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  s less than the 
36680 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64  value of the 3rd
36690 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74  .** parameter, t
366a0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
366b0 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f  g string will co
366c0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
366d0 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72  ULs and the.** r
366e0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
366f0 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  ions operating o
36700 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65  n strings with e
36710 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
36720 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49  undefined..** ^I
36730 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
36740 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
36750 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
36760 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
36770 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36780 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
36790 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
367a0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
367b0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
367c0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
367d0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
367e0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
367f0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
36800 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
36810 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
36820 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
36830 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
36840 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36850 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
36860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36870 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
36880 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
36890 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
368a0 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
368b0 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
368c0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
368d0 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
368e0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
368f0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
36900 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
36910 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
36920 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
36930 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
36940 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
36950 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
36960 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
36970 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
36980 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
36990 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
369a0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
369b0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
369c0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
369d0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
369e0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
369f0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
36a00 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
36a10 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
36a20 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
36a30 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
36a40 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
36a50 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
36a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36a70 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
36a80 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
36a90 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
36aa0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36ab0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36ac0 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
36ad0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36ae0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36af0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
36b00 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
36b10 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
36b20 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
36b30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
36b40 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
36b50 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
36b60 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
36b70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
36b80 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
36b90 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
36ba0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
36bb0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
36bc0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
36bd0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
36be0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
36bf0 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
36c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36c10 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
36c20 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
36c30 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
36c40 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
36c50 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
36c60 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
36c70 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
36c80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36c90 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
36ca0 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
36cb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
36cc0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
36cd0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
36ce0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
36cf0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
36d00 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
36d10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36d20 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36d30 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
36d40 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
36d50 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
36d60 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
36d70 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
36d80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36d90 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
36da0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
36db0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
36dc0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
36dd0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36de0 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  t_blob64(sqlite3
36df0 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20  _context*,const 
36e00 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20  void*,.         
36e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36e20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34    sqlite3_uint64
36e30 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
36e40 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36e50 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
36e60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
36e70 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
36e80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36e90 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
36ea0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
36eb0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
36ec0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36ed0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
36ee0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36ef0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
36f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36f10 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
36f20 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
36f30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36f40 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
36f50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
36f60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36f70 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
36f80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36f90 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36fa0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
36fb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36fc0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36fd0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
36fe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36ff0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
37000 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37010 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
37020 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
37030 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37040 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
37050 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
37060 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
37070 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37080 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37090 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63  text64(sqlite3_c
370a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
370b0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
370c0 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
370d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
370e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
370f0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
37100 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71  coding);.void sq
37110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37120 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
37130 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
37140 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
37150 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
37160 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37170 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
37180 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
37190 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
371a0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
371b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
371c0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
371d0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
371e0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
371f0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
37200 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
37210 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
37220 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
37230 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
37240 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
37250 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
37260 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
37270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37280 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
37290 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
372a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
372b0 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
372c0 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
372d0 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
372e0 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
372f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37300 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
37310 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
37320 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
37330 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
37340 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
37350 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
37360 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
37370 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
37380 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
37390 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
373a0 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
373b0 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
373c0 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
373d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
373e0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
373f0 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
37400 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
37410 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
37420 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
37430 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
37440 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
37450 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
37460 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
37470 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
37480 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
37490 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
374a0 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
374b0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
374c0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
374d0 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
374e0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
374f0 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
37500 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
37510 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
37520 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
37530 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
37540 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
37550 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
37560 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
37570 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
37580 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
37590 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
375a0 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
375b0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
375c0 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
375d0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
375e0 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
375f0 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
37600 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
37610 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
37620 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
37630 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
37640 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
37650 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
37660 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
37670 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
37680 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
37690 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
376a0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
376b0 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63  rg, is an applic
376c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
376d0 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
376e0 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
376f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
37700 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
37710 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
37720 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
37730 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
37740 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
37750 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
37760 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37770 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
37780 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37790 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
377a0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
377b0 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
377c0 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
377d0 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
377e0 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
377f0 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
37800 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
37810 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
37820 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
37830 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
37840 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
37850 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
37860 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
37870 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37880 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
37890 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
378a0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
378b0 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
378c0 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
378d0 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
378e0 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
378f0 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
37900 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
37910 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
37920 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
37930 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
37940 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
37950 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
37960 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
37970 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
37980 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
37990 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
379a0 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
379b0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
379c0 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
379d0 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
379e0 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
379f0 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
37a00 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
37a10 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
37a20 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
37a30 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
37a40 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
37a50 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
37a60 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
37a70 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
37a80 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
37a90 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
37aa0 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
37ab0 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
37ac0 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
37ad0 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
37ae0 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
37af0 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
37b00 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
37b10 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
37b20 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
37b30 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
37b40 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
37b50 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
37b60 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
37b70 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
37b80 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37b90 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
37ba0 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
37bb0 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
37bc0 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
37bd0 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
37be0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
37bf0 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
37c00 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
37c10 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
37c20 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
37c30 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
37c40 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
37c50 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
37c60 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
37c70 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
37c80 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
37c90 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
37ca0 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
37cb0 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
37cc0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37cd0 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
37ce0 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
37cf0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
37d00 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
37d10 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
37d20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37d30 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
37d40 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
37d50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37d60 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65  on().** with the
37d70 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74   addition that t
37d80 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
37d90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
37da0 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20  on pArg when.** 
37db0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
37dc0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
37dd0 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67  d..** ^Collating
37de0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64   functions are d
37df0 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79  eleted when they
37e00 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
37e10 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c  by later.** call
37e20 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
37e30 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
37e40 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
37e50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
37e60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
37e70 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
37e80 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
37e90 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f  .** ^The xDestro
37ea0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75  y callback is <u
37eb0 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20  >not</u> called 
37ec0 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74  if the .** sqlit
37ed0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37ee0 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f  ion_v2() functio
37ef0 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63  n fails.  Applic
37f00 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f  ations that invo
37f10 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  ke.** sqlite3_cr
37f20 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37f30 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  2() with a non-N
37f40 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67  ULL xDestroy arg
37f50 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  ument should .**
37f60 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
37f70 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f  n code and dispo
37f80 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  se of the applic
37f90 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
37fa0 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73  er.** themselves
37fb0 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70   rather than exp
37fc0 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  ecting SQLite to
37fd0 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f   deal with it fo
37fe0 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20  r them..** This 
37ff0 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  is different fro
38000 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51  m every other SQ
38010 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
38020 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e   The inconsisten
38030 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74  cy .** is unfort
38040 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74  unate but cannot
38050 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68   be changed with
38060 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63  out breaking bac
38070 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61  kwards .** compa
38080 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
38090 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
380a0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
380b0 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
380c0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
380d0 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
380e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
380f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
38100 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
38110 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
38120 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
38130 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
38140 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
38150 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
38160 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
38170 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
38180 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
38190 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
381a0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
381b0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
381c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
381d0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
381e0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
381f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
38200 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
38210 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
38220 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
38230 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
38240 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
38250 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
38260 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
38270 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
38280 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
38290 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
382a0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
382b0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
382c0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
382d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
382e0 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
382f0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
38300 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
38310 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
38320 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
38330 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
38340 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
38350 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
38360 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
38370 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
38380 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
38390 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
383a0 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
383b0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
383c0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
383d0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
383e0 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
383f0 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
38400 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
38410 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
38420 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
38430 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
38440 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
38450 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
38460 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
38470 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
38480 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
38490 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
384a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
384b0 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
384c0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
384d0 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
384e0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
384f0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
38500 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
38510 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
38520 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
38530 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
38540 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
38550 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
38560 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
38570 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
38580 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
38590 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
385a0 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
385b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
385c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
385d0 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
385e0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
385f0 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
38600 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
38610 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
38620 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
38630 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
38640 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
38650 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
38660 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
38670 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
38680 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
38690 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
386a0 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
386b0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
386c0 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
386d0 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
386e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
386f0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
38700 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
38710 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
38720 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
38730 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
38740 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
38750 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
38760 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
38770 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38780 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
38790 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
387a0 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
387b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72