/ Hex Artifact Content
Login

Artifact f97f23de94767ab7e2c97745308920a749d4a4b5:


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 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
2af0: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
2b00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2b10: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
2b20: 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73  se_v2() routines
2b30: 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73   are destructors
2b40: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  .** for the [sql
2b50: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2b60: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2b70: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2b80: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2b90: 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  ) return [SQLITE
2ba0: 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b  _OK] if.** the [
2bb0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2bc0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  is successfully 
2bd0: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c  destroyed and al
2be0: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  l associated.** 
2bf0: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65  resources are de
2c00: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  allocated..**.**
2c10: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
2c20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2c30: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2c60: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  ts or unfinished
2c70: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2c80: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c  objects then sql
2c90: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20  ite3_close().** 
2ca0: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64  will leave the d
2cb0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cc0: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75  on open and retu
2cd0: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
2ce0: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
2cf0: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
2d00: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e  alled with unfin
2d10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20  alized prepared 
2d20: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e  statements.** an
2d30: 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20  d/or unfinished 
2d40: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c  sqlite3_backups,
2d50: 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
2d60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  se connection be
2d70: 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73  comes.** an unus
2d80: 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68  able "zombie" wh
2d90: 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ich will automat
2da0: 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f  ically be deallo
2db0: 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a  cated when the.*
2dc0: 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20  * last prepared 
2dd0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2de0: 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61  alized or the la
2df0: 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  st sqlite3_backu
2e00: 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64  p is.** finished
2e10: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  .  The sqlite3_c
2e20: 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66  lose_v2() interf
2e30: 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
2e40: 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20  for use with.** 
2e50: 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74  host languages t
2e60: 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20  hat are garbage 
2e70: 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77  collected, and w
2e80: 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69  here the order i
2e90: 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72  n which.** destr
2ea0: 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65  uctors are calle
2eb0: 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  d is arbitrary..
2ec0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2ed0: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2ee0: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2ef0: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2f00: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2f10: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2f20: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2f30: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2f40: 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b  dles], and .** [
2f50: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66  sqlite3_backup_f
2f60: 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20  inish | finish] 
2f70: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  all [sqlite3_bac
2f80: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73  kup] objects ass
2f90: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
2fa0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2fb0: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2fc0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2fd0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2fe0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2ff0: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
3000: 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73  ed on a [databas
3010: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
3020: 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20  at still has.** 
3030: 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65  outstanding [pre
3040: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
3050: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
3060: 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71  ], and/or.** [sq
3070: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
3080: 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65  jects then it re
3090: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
30a0: 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f  ] and the deallo
30b0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73  cation.** of res
30c0: 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72  ources is deferr
30d0: 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72  ed until all [pr
30e0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30f0: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3100: 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  s],.** and [sqli
3110: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
3120: 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73  cts are also des
3130: 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  troyed..**.** ^I
3140: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  f an [sqlite3] o
3150: 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79  bject is destroy
3160: 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73  ed while a trans
3170: 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a  action is open,.
3180: 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ** the transacti
3190: 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  on is automatica
31a0: 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  lly rolled back.
31b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72  .**.** The C par
31c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
31d0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64  e3_close(C)] and
31e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
31f0: 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  v2(C)].** must b
3200: 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a  e either a NULL.
3210: 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e  ** pointer or an
3220: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3230: 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e  t pointer obtain
3240: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
3250: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
3260: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
3270: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
3280: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
3290: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
32a0: 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69  losed..** ^Calli
32b0: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  ng sqlite3_close
32c0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c  () or sqlite3_cl
32d0: 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ose_v2() with a 
32e0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
32f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61  argument is a ha
3300: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
3310: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f  .int sqlite3_clo
3320: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e  se(sqlite3*);.in
3330: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  t sqlite3_close_
3340: 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  v2(sqlite3*);../
3350: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
3360: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
3370: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
3380: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
3390: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
33a0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
33b0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
33c0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
33d0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
33e0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
33f0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
3400: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3410: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
3420: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
3430: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
3440: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
3450: 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
3460: 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
3470: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
3480: 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e  terface is a con
3490: 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72  venience wrapper
34a0: 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
34b0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
34c0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
34d0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
34e0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a  3_finalize()],.*
34f0: 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e  * that allows an
3500: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
3510: 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61  run multiple sta
3520: 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a  tements of SQL.*
3530: 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  * without having
3540: 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66   to use a lot of
3550: 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20   C code. .**.** 
3560: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65  ^The sqlite3_exe
3570: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75  c() interface ru
3580: 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ns zero or more 
3590: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a  UTF-8 encoded,.*
35a0: 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
35b0: 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  rate SQL stateme
35c0: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20  nts passed into 
35d0: 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
35e0: 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74  ,.** in the cont
35f0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
3600: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3610: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74   passed in as it
3620: 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  s 1st.** argumen
3630: 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  t.  ^If the call
3640: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66  back function of
3650: 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
3660: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3670: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
3680: 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69  LL, then it is i
3690: 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20  nvoked for each 
36a0: 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f  result row.** co
36b0: 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20  ming out of the 
36c0: 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74  evaluated SQL st
36d0: 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20  atements.  ^The 
36e0: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  4th argument to.
36f0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3700: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
3710: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
3720: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
3730: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3740: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3750: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3760: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3770: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3780: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3790: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
37a0: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
37b0: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
37c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
37d0: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
37e0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
37f0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3800: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
3810: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
3820: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
3830: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3840: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3850: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3860: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3870: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3880: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3890: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
38a0: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
38b0: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
38c0: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
38d0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
38e0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
38f0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
3900: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
3910: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
3920: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
3930: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3940: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3950: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3960: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3970: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3980: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3990: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
39a0: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
39b0: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
39d0: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
39e0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
39f0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
3a00: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
3a10: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a20: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3a30: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3a40: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3a50: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3a60: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3a70: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3a80: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3a90: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3aa0: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3ab0: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3ac0: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3ad0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
3ae0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3af0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
3b00: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
3b10: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
3b20: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
3b30: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3b40: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3b50: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3b60: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3b70: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3b80: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3b90: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3ba0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3bb0: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3bc0: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3bd0: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
3be0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3bf0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3c00: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
3c10: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
3c20: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
3c30: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3c40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3c50: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3c60: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3c70: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3c80: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3c90: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3ca0: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3cb0: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3cc0: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3cd0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3ce0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
3cf0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
3d00: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
3d10: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3d20: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3d30: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3d40: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3d50: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3d60: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3d70: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3d80: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3d90: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3da0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3db0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3dc0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3dd0: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3de0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3df0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
3e00: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
3e10: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
3e20: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
3e30: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3e40: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3e50: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3e60: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3e70: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3e80: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3e90: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3ea0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3eb0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3ec0: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3ed0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
3ee0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3ef0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
3f00: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
3f10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3f20: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
3f30: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3f40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3f50: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3f60: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3f70: 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64  not close the [d
3f80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3f90: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3fa0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3fb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3fc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3fd0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3fe0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3ff0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4000: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
4010: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
4020: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
4030: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
4040: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4050: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
4060: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
4070: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
4080: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
4090: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
40a0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
40e0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
40f0: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4120: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4130: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4140: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4150: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4160: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4170: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
41b0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
41c0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
41f0: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4200: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4210: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4220: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4230: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
4240: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4250: 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c  }.**.** Many SQL
4260: 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ite functions re
4270: 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20  turn an integer 
4280: 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d  result code from
4290: 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a   the set shown.*
42a0: 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20  * here in order 
42b0: 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 63  to indicate succ
42c0: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a  ess or failure..
42d0: 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20  **.** New error 
42e0: 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64  codes may be add
42f0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
4300: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
4310: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
4320: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
4330: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4340: 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ns].*/.#define S
4350: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
4360: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
4370: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
4380: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
4390: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
43a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
43b0: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
43c0: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
43d0: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
43e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43f0: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
4400: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
4410: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
4420: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
4430: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
4440: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
4450: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
4460: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4470: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
4480: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
4490: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
44a0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
44b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
44c0: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
44d0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
44e0: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
44f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4500: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
4510: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
4520: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
4530: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4540: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
4550: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
4560: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
4570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4580: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
4590: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
45a0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
45b0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
45c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
45d0: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
45e0: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
45f0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
4600: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4620: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
4630: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
4640: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
4650: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
4660: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
4670: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
4680: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
4690: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
46a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46b0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
46c0: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
46d0: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
46e0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
46f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4700: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
4710: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
4720: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
4730: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
4760: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
4770: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
4780: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4790: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
47a0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
47b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
47c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
47e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
47f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4800: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4810: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4820: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4830: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4840: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4850: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4860: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4870: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4880: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
48a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
48b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
48c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
48d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
48e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
48f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4900: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4910: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4920: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4930: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4940: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4960: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4970: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4980: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4990: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
49a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
49b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
49c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
49d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
49e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
49f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4a00: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4a10: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4a20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4a30: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4a40: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4a50: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4a60: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4a80: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4a90: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
4aa0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
4ab0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
4ad0: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e  E      27   /* N
4ae0: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f  otifications fro
4af0: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b10: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38  E_WARNING     28
4b20: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66     /* Warnings f
4b30: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4b40: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4b50: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4b60: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4b70: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4b80: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4ba0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4bb0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4bc0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4bd0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4be0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4bf0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4c00: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4c10: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4c20: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4c30: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64  ed result code d
4c40: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4c50: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
4c60: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
4c70: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
4c80: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
4c90: 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 30 integer.** 
4ca0: 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20  [result codes]. 
4cb0: 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69   However, experi
4cc0: 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74  ence has shown t
4cd0: 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74  hat many of.** t
4ce0: 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65  hese result code
4cf0: 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65  s are too coarse
4d00: 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20  -grained.  They 
4d10: 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  do not provide a
4d20: 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d  s.** much inform
4d30: 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62  ation about prob
4d40: 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d  lems as programm
4d50: 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20  ers might like. 
4d60: 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f   In an effort to
4d70: 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73  .** address this
4d80: 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  , newer versions
4d90: 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73   of SQLite (vers
4da0: 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61  ion 3.3.8 and la
4db0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
4dc0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
4dd0: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
4de0: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
4df0: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
4e00: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
4e10: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73  out errors. Thes
4e20: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  e [extended resu
4e30: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e  lt codes] are en
4e40: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4e50: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4e60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4e70: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4e80: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4e90: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4ea0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c  des()] API.  Or,
4eb0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f   the extended co
4ec0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f  de for.** the mo
4ed0: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20  st recent error 
4ee0: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
4ef0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
4f00: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
4f10: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  de()]..*/.#defin
4f20: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4f30: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
4f40: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f50: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
4f60: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f70: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
4f80: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f90: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
4fa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
4fb0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
4fc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4fd0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
4fe0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
4ff0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5000: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5010: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5020: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5030: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5040: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5050: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
5070: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
50b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
5190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51a0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
51b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
51c0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
51d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51e0: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
51f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5200: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5220: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5230: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5240: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5260: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
5270: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
5280: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
5290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52a0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
52b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52c0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
52d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52e0: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
52f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5300: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5320: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5330: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5340: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5360: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
5370: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5380: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
5390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53a0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
53b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53c0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
53d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53e0: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
53f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5400: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
5410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5420: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
5430: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5440: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5460: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
5470: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5480: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
5490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54a0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
54b0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
54c0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20  IOERR_MMAP      
54f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5500: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29  IOERR | (24<<8))
5510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5520: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54  IOERR_GETTEMPPAT
5530: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5540: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29  IOERR | (25<<8))
5550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5560: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20  IOERR_CONVPATH  
5570: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5580: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29  IOERR | (26<<8))
5590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55a0: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
55b0: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
55c0: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5600: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
5610: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5620: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20  E_BUSY_SNAPSHOT 
5630: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5640: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c  E_BUSY   |  (2<<
5650: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5660: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
5670: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
5680: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5690: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
56b0: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
56c0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
56d0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
56e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
56f0: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28  FULLPATH       (
5700: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5710: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5720: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5730: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  N_CONVPATH      
5740: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5750: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  N | (4<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
5770: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  PT_VTAB         
5780: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55     (SQLITE_CORRU
5790: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  PT | (1<<8)).#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
57b0: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20  ONLY_RECOVERY   
57c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
57d0: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23  ONLY | (1<<8)).#
57e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
57f0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20  ADONLY_CANTLOCK 
5800: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5810: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29  ADONLY | (2<<8))
5820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5830: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43  READONLY_ROLLBAC
5840: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5850: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38  READONLY | (3<<8
5860: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5870: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56  E_READONLY_DBMOV
5880: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ED        (SQLIT
5890: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c  E_READONLY | (4<
58a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58b0: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
58d0: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5900: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5910: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5920: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5930: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5940: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5950: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5960: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5970: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5980: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5990: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
59a0: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
59b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
59c0: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
59d0: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
59e0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
59f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5a10: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5a20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5a30: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5a40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a50: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5a60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a70: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a90: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5aa0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ab0: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ad0: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5ae0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5af0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5b00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5b20: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b40: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5b50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b60: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
5b70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b80: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
5b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5ba0: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
5bb0: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
5bc0: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
5bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5be0: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
5bf0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
5c00: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
5c10: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
5c20: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
5c30: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
5c40: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
5c60: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
5c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
5c80: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5c90: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5ca0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5cb0: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5cc0: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5cd0: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5ce0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5cf0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5d00: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5d10: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5d20: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5d30: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5d40: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d50: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5d60: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5d70: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5d80: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5d90: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5da0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5db0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5dc0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5dd0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5de0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5df0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5e00: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5e10: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5e20: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5e30: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
5e40: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5e50: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5e60: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
5e70: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
5e80: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
5e90: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5ea0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
5eb0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
5ec0: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
5ed0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5ee0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
5ef0: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
5f00: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
5f10: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
5f20: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
5f30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5f40: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
5f50: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5f60: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5f70: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
5f80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5f90: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
5fa0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fb0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fc0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
5fd0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5fe0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
5ff0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6000: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
6010: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
6020: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
6030: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6040: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
6050: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
6060: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6070: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6080: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6090: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
60a0: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
60b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
60d0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
60e0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
60f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6100: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
6110: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
6120: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
6130: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6140: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6150: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
6160: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6170: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6180: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6190: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
61a0: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
61b0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
61c0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
61d0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
61e0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
61f0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
6200: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6210: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6220: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
6230: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6240: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
6250: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6260: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6270: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6280: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6290: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
62a0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
62b0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
62d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
62e0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
62f0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
6300: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6310: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6320: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
6330: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6340: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6350: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6360: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6370: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
6380: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6390: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
63a0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
63b0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
63c0: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
63d0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
63e0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
63f0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6400: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6410: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6420: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
6430: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6440: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6450: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
6460: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6470: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
6480: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
6490: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
64a0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
64b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
64c0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
64d0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
64e0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
64f0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6500: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6510: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6520: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
6530: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6540: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6550: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6560: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6570: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6580: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6590: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
65a0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
65b0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
65c0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
65d0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
65e0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
65f0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6600: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6610: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6620: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6630: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6640: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6650: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6660: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6670: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6680: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6690: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
66a0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
66b0: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
66c0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
66d0: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
66e0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
66f0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6700: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6710: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6720: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
6730: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6740: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6750: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6760: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6770: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6780: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6790: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
67a0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
67b0: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
67c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
67d0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
67e0: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
67f0: 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65  cate that a file
6800: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6810: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6820: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6830: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6840: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6850: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6860: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
6870: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
6880: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
6890: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
68a0: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
68b0: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
68c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
68d0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
68e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
68f0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6900: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6910: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6920: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6930: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6940: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6950: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6970: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6980: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6990: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
69a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
69b0: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
69c0: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
69d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69e0: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
69f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a00: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6a10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a20: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6a30: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6a40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a50: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6a60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6a70: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6a80: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6a90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6aa0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6ab0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6ac0: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6ad0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6af0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6b00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b10: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6b20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6b30: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6b40: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6b50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b60: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6b70: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6b80: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6b90: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6ba0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6bb0: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6bc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6bd0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6be0: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6bf0: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6c00: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c10: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6c20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6c30: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6c40: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6c50: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6c60: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6c70: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6c80: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6c90: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6ca0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6cc0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6cd0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6ce0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6cf0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6d00: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6d10: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6d20: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6d30: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6d40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6d50: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6d60: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6d70: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6d80: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6d90: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6da0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6db0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6dc0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6dd0: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6de0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6df0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6e00: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6e10: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6e20: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6e30: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6e40: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6e50: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6e60: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6e70: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6e80: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6e90: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6ea0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6eb0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6ec0: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6ed0: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6ee0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6ef0: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6f00: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6f10: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6f20: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6f30: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6f40: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6f50: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6f60: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6f70: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6f80: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6f90: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6fa0: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6fb0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6fc0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6fd0: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6fe0: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6ff0: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
7000: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
7010: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
7020: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
7030: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
7040: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
7050: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
7060: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
7070: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
7080: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
7090: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
70a0: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
70b0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70c0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
70d0: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
70e0: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
70f0: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
7100: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
7110: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7120: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
7130: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
7140: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
7150: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7160: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7170: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
7180: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7190: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
71a0: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
71b0: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
71c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
71d0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
71e0: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
71f0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
7200: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
7210: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7220: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
7230: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
7240: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
7250: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7260: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7270: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
7280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7290: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
72a0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
72b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
72c0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
72d0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
72e0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
72f0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7300: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
7310: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7320: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
7330: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
7340: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
7350: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7360: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7370: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7380: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7390: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
73a0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
73b0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
73c0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
73d0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
73e0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
73f0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7400: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7410: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7420: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7430: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7440: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
7450: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7460: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7470: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7480: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7490: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
74a0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
74b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
74c0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
74d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
74e0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
74f0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7500: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7510: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7520: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7530: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7540: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
7550: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7560: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7570: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7580: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7590: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
75a0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
75b0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
75c0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
75d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
75e0: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
75f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7600: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7610: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7620: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7630: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7640: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
7650: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7660: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7670: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7680: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7690: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
76a0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
76b0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
76c0: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
76d0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
76e0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
76f0: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7700: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7710: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7720: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7730: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7740: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
7750: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7760: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7770: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7780: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7790: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
77a0: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
77b0: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
77c0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
77d0: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
77e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
77f0: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7810: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7820: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7830: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7840: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7850: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7860: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7870: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7880: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7890: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
78a0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
78b0: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
78c0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
78d0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
78e0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
78f0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7900: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7910: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7920: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7930: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7940: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7950: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7960: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7970: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7980: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7990: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
79a0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
79b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
79c0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
79d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
79e0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
79f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7a00: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7a10: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7a20: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7a30: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7a40: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7a50: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7a60: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7a70: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7a80: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7a90: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7aa0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7ab0: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
7ac0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7ad0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7ae0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7af0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7b00: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7b10: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7b20: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7b30: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7b40: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7b50: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7b60: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7b70: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7b80: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7b90: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7ba0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7bb0: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7bc0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7bd0: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7be0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7bf0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7c00: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7c10: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7c20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7c30: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7c40: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7c50: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7c60: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7c70: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7c80: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7c90: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7ca0: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7cb0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7cc0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7cd0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7ce0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7cf0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7d00: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7d10: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7d20: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7d30: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7d40: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7d50: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7d60: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7d70: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7d80: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7d90: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7da0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7db0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7dc0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7dd0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7de0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7df0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7e00: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7e10: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7e20: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7e30: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7e40: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
7e50: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
7e60: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7e70: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7e80: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7e90: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7ea0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7eb0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7ec0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7ed0: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7ee0: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7ef0: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7f00: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7f10: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7f20: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7f30: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7f40: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7f50: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7f60: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7f70: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7f80: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7f90: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7fa0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7fb0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7fc0: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7fd0: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7fe0: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7ff0: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
8000: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
8010: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
8020: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
8030: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
8040: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
8050: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
8060: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8070: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
8080: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
8090: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
80a0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
80b0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
80c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
80d0: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
80e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
80f0: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
8100: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8110: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
8120: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8130: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
8140: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8150: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
8160: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8170: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
8180: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8190: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
81c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81d0: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
81e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81f0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8200: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8210: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8220: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
8230: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8240: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
8250: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
8260: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
8270: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
8280: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8290: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
82a0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
82b0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
82c0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
82d0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
82e0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
82f0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8300: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8310: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8320: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8330: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8340: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
8350: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
8360: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
8370: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
8380: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
8390: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
83a0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
83b0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
83c0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
83d0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
83e0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
83f0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8400: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8410: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8420: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8430: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8440: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8450: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8460: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8470: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
8480: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
8490: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
84a0: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
84b0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
84c0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
84d0: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
84e0: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
84f0: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8500: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8510: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8520: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8530: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8540: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8550: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8560: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8570: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
8580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
8590: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
85a0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
85b0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
85c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
85d0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
85e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
85f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8600: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8610: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8620: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8630: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8640: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8650: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8660: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8670: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8680: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8690: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
86a0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
86b0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
86c0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
86d0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
86e0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
86f0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8700: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8710: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8720: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8730: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8740: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8750: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8760: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8770: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8780: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
8790: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
87a0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
87b0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
87c0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
87d0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
87e0: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
87f0: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8810: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8820: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8850: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8860: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8870: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
8880: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8890: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
88a0: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
88b0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
88c0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
88d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
88e0: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
88f0: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8900: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8910: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8920: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8930: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8940: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8950: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8960: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8970: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
8980: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
8990: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
89a0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
89b0: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
89c0: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
89d0: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
89e0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
89f0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8a00: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8a10: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8a20: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8a30: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
8a40: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
8a50: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8a60: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
8a70: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
8a80: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
8a90: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8aa0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8ab0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
8ac0: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
8ad0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
8ae0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8af0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8b00: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8b10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8b20: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8b30: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8b40: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8b50: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8b60: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8b70: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8b80: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8b90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
8ba0: 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65  CKSTATE]].** The
8bb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8bc0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8bd0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8be0: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8bf0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8c00: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8c10: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8c20: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8c30: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8c40: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
8c50: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
8c60: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8c70: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8c80: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8c90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8ca0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8cb0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8cc0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8cd0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8ce0: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8cf0: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8d00: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8d10: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8d20: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
8d30: 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53  lable when the S
8d40: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f  QLITE_TEST.** co
8d50: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
8d60: 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
8d70: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8d80: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
8d90: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8da0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
8db0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
8dc0: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
8dd0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
8de0: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
8df0: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
8e00: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
8e10: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
8e20: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
8e30: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
8e40: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
8e50: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
8e60: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
8e70: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
8e80: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
8e90: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
8ea0: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
8eb0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8ec0: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
8ed0: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
8ee0: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
8ef0: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
8f00: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
8f10: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
8f20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8f30: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
8f40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8f50: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
8f60: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8f70: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
8f80: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
8f90: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
8fa0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8fb0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
8fc0: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
8fd0: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
8fe0: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
8ff0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
9000: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
9010: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
9020: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
9030: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
9040: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
9050: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
9060: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
9070: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
9080: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
9090: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
90a0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
90b0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
90c0: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
90d0: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
90e0: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
90f0: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
9100: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
9110: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
9120: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9130: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
9140: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9150: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
9160: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9170: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9180: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9190: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
91a0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
91b0: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
91c0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
91d0: 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20  ction.  See the 
91e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
91f0: 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e  ntrol()] documen
9200: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64  tation for.** ad
9210: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
9220: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
9230: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9240: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9250: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9260: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9270: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9280: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9290: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
92a0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
92b0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
92c0: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
92d0: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
92e0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
92f0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
9300: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
9310: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
9320: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
9330: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9340: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9350: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9360: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9370: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9380: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9390: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
93a0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
93b0: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
93c0: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
93d0: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
93e0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
93f0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
9400: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
9410: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9420: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9430: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9440: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9450: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9460: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9470: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9480: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9490: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
94a0: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
94b0: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
94c0: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
94d0: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
94e0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
94f0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
9500: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
9510: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9520: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9530: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9540: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9550: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9560: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9570: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9580: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9590: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
95a0: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
95b0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
95c0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
95d0: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
95e0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
95f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9600: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
9610: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9620: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9630: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9640: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9650: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9660: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9670: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9680: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9690: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
96a0: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
96b0: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
96c0: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
96d0: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
96e0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
96f0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9700: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9710: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9720: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9730: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9740: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9750: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9760: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9770: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9780: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9790: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
97a0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
97b0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
97c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
97d0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
97e0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
97f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9800: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9810: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9820: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9830: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9840: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9850: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9860: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9870: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9880: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9890: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
98a0: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
98b0: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
98c0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
98d0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
98e0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
98f0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9900: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9910: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9920: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9930: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
9940: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
9950: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
9960: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
9970: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
9980: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
9990: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
99a0: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
99b0: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
99c0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
99d0: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
99e0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
99f0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
9a00: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9a10: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
9a20: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
9a30: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
9a40: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
9a50: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
9a60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
9a70: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
9a80: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9a90: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9aa0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9ab0: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9ac0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9ad0: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9ae0: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9af0: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9b00: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9b10: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9b20: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9b30: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9b40: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9b50: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9b60: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
9b70: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
9b80: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9b90: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9ba0: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
9bb0: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
9bc0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9bd0: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9be0: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9bf0: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9c00: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9c10: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9c20: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9c30: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
9c40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9c50: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
9c60: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
9c70: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
9c80: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
9c90: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
9ca0: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
9cb0: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
9cc0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9cd0: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9ce0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9cf0: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9d00: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9d10: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9d20: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
9d30: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
9d40: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
9d50: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
9d60: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
9d70: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
9d80: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
9d90: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
9da0: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
9db0: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
9dc0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9dd0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9de0: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9df0: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9e00: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9e10: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9e20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9e30: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
9e40: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
9e50: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
9e60: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
9e70: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
9e80: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
9e90: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
9ea0: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
9eb0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
9ec0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9ed0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9ee0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9ef0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9f00: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9f10: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9f20: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9f30: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
9f40: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
9f50: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
9f60: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
9f70: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
9f80: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9f90: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9fa0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9fb0: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
9fc0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9fd0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9fe0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9ff0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
a000: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a010: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
a020: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
a030: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a040: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a050: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
a060: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
a070: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
a080: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
a090: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
a0a0: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
a0b0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
a0c0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
a0d0: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
a0e0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
a0f0: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
a100: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
a110: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
a120: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
a130: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
a140: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
a150: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
a160: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
a170: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
a180: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a190: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
a1a0: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
a1b0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
a1c0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
a1d0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
a1e0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
a1f0: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
a200: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
a210: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a220: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a230: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
a240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a250: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
a260: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a270: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
a280: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
a290: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
a2a0: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
a2b0: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
a2c0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
a2d0: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
a2e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
a2f0: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
a300: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
a310: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
a320: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
a330: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
a340: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
a350: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a360: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
a370: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a380: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
a390: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
a3a0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
a3b0: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
a3c0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
a3d0: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
a3e0: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
a3f0: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
a400: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
a410: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
a420: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
a430: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
a440: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
a450: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
a460: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
a470: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
a480: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
a490: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
a4a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a4b0: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
a4c0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
a4d0: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
a4e0: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
a4f0: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
a500: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
a510: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
a520: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
a530: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
a540: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
a550: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
a560: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
a570: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
a580: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
a590: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
a5a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
a5b0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
a5c0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
a5d0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
a5e0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
a5f0: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
a600: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
a610: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
a620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a630: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
a640: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
a650: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
a660: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
a670: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
a680: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
a690: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
a6a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
a6b0: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
a6c0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
a6d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
a6e0: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
a6f0: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
a700: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
a710: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
a720: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a730: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a740: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
a750: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
a760: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
a770: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
a780: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
a790: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
a7a0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
a7b0: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
a7c0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
a7d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
a7e0: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
a7f0: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
a800: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
a810: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
a820: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
a830: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
a840: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
a850: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
a860: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
a870: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
a880: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
a890: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
a8a0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
a8b0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
a8c0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
a8d0: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
a8e0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
a8f0: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
a900: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
a910: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
a920: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
a930: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
a940: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
a950: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a960: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
a970: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
a980: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
a990: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
a9a0: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
a9b0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
a9c0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
a9d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a9e0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
a9f0: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
aa00: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
aa10: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
aa20: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
aa30: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
aa40: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
aa50: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
aa60: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
aa70: 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  if result string
aa80: 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61   is NULL, or tha
aa90: 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  t returns a copy
aaa0: 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
aab0: 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20  t string if the 
aac0: 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55  string is non-NU
aad0: 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  LL..** ^If the [
aae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aaf0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
ab00: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
ab10: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
ab20: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
ab30: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
ab40: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
ab50: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
ab60: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
ab70: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
ab80: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
ab90: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
aba0: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
abb0: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
abc0: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
abd0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
abe0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
abf0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
ac00: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
ac10: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
ac20: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
ac30: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
ac40: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
ac50: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
ac60: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
ac70: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
ac80: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ac90: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  DLER]].** ^The [
aca0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
acb0: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c  YHANDLER].** fil
acc0: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
acd0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
ace0: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
acf0: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
ad00: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
ad10: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
ad20: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
ad30: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
ad40: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
ad50: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
ad60: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
ad70: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
ad80: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
ad90: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
ada0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
adb0: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
adc0: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
add0: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
ade0: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
adf0: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
ae00: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
ae10: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
ae20: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ae30: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
ae40: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
ae50: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
ae60: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
ae70: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
ae80: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
ae90: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
aea0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
aeb0: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
aec0: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
aed0: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
aee0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aef0: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
af00: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
af10: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
af20: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
af30: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
af40: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
af50: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
af60: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
af70: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
af80: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
af90: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
afa0: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
afb0: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
afc0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
afd0: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
afe0: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
aff0: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
b000: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
b010: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
b020: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
b030: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
b040: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
b050: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
b060: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
b070: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
b080: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
b090: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
b0a0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
b0b0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
b0c0: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
b0d0: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
b0e0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
b0f0: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
b100: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
b110: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
b120: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b130: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b140: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b150: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b160: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
b170: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72   is used to quer
b180: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20  y or set the.** 
b190: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b1a0: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c  f bytes that wil
b1b0: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65  l be used for me
b1c0: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e  mory-mapped I/O.
b1d0: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
b1e0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
b1f0: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65   a value of type
b200: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74   sqlite3_int64 t
b210: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76  hat.** is an adv
b220: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75  isory maximum nu
b230: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
b240: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d   the file to mem
b250: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a  ory map.  The.**
b260: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72   pointer is over
b270: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
b280: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65   old value.  The
b290: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68   limit is not ch
b2a0: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20  anged if.** the 
b2b0: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79  value originally
b2c0: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e   pointed to is n
b2d0: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20  egative, and so 
b2e0: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69  the current limi
b2f0: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65  t .** can be que
b300: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
b310: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
b320: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
b330: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65  r.  This.** file
b340: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64  -control is used
b350: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
b360: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
b370: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a   mmap_size]..**.
b380: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b390: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a  FCNTL_TRACE]].**
b3a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b3b0: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63  TL_TRACE] file c
b3c0: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20  ontrol provides 
b3d0: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61  advisory informa
b3e0: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56  tion.** to the V
b3f0: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68  FS about what th
b400: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20  e higher layers 
b410: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74  of the SQLite st
b420: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a  ack are doing..*
b430: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
b440: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73  rol is used by s
b450: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79  ome VFS activity
b460: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d   tracing [shims]
b470: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b480: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t is a zero-term
b490: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20  inated string.  
b4a0: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e  Higher layers in
b4b0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73   the.** SQLite s
b4c0: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74  tack may generat
b4d0: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74  e instances of t
b4e0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b4f0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49   if.** the [SQLI
b500: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41  TE_USE_FCNTL_TRA
b510: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
b520: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
b530: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b540: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
b550: 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20  _MOVED]].** The 
b560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b570: 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f  S_MOVED] file co
b580: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
b590: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
b5a0: 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
b5b0: 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20   an integer and 
b5c0: 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c  it writes a bool
b5d0: 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  ean into that in
b5e0: 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a  teger depending.
b5f0: 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72  ** on whether or
b600: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61   not the file ha
b610: 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20  s been renamed, 
b620: 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65  moved, or delete
b630: 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61  d since it.** wa
b640: 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a  s first opened..
b650: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b660: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
b670: 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54  ET_HANDLE]].** T
b680: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b690: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
b6a0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
b6b0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
b6c0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
b6d0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
b6e0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
b6f0: 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65  to swap the file
b700: 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65   handle with the
b710: 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20   one.** pointed 
b720: 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61  to by the pArg a
b730: 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63  rgument.  This c
b740: 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65  apability is use
b750: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
b760: 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  .** and only nee
b770: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
b780: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
b790: 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  EST is defined..
b7a0: 2a 2a 0a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  **.* <li>[[SQLIT
b7b0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
b7c0: 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  K]].** The [SQLI
b7d0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
b7e0: 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20  CK] is a signal 
b7f0: 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72  to the VFS layer
b800: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a   that it might.*
b810: 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75  * be advantageou
b820: 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68  s to block on th
b830: 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20  e next WAL lock 
b840: 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e  if the lock is n
b850: 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ot immediately.*
b860: 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68  * available.  Th
b870: 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20  e WAL subsystem 
b880: 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e  issues this sign
b890: 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a  al during rare.*
b8a0: 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  * circumstances 
b8b0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20  in order to fix 
b8c0: 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70  a problem with p
b8d0: 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f  riority inversio
b8e0: 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  n..** Applicatio
b8f0: 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f  ns should <em>no
b900: 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20  t</em> use this 
b910: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a  file-control..**
b920: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b930: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a  _FCNTL_ZIPVFS]].
b940: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b950: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63  CNTL_ZIPVFS] opc
b960: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
b970: 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c  ed by zipvfs onl
b980: 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  y. All other.** 
b990: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
b9a0: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
b9b0: 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  D for this opcod
b9c0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
b9d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 54 41 5d  QLITE_FCNTL_OTA]
b9e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b9f0: 5f 46 43 4e 54 4c 5f 4f 54 41 5d 20 6f 70 63 6f  _FCNTL_OTA] opco
ba00: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
ba10: 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c  d by the special
ba20: 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20   VFS used by.** 
ba30: 74 68 65 20 4f 54 41 20 65 78 74 65 6e 73 69 6f  the OTA extensio
ba40: 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68  n only.  All oth
ba50: 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  er VFS should re
ba60: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
ba70: 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73  OUND for.** this
ba80: 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f   opcode.  .** </
ba90: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
baa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
bab0: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
bac0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
bad0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
bae0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
baf0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
bb00: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
bb10: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
bb20: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
bb30: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
bb40: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
bb50: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
bb60: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
bb70: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
bb80: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
bb90: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
bba0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
bbb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bbc0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
bbd0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
bbe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bbf0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
bc00: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
bc10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bc20: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
bc30: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
bc40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc50: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
bc60: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
bc70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc80: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
bc90: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
bca0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bcb0: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
bcc0: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
bcd0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bce0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
bcf0: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
bd00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
bd10: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
bd20: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
bd30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
bd40: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
bd50: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
bd60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
bd70: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
bd80: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
bd90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
bda0: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
bdb0: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
bdc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
bdd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bde0: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
bdf0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
be00: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
be10: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
be20: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
be30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
be40: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
be50: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
be60: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
be70: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
be80: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
be90: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33  _HANDLE       23
bea0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
beb0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20  FCNTL_WAL_BLOCK 
bec0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a               24.
bed0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bee0: 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20  CNTL_ZIPVFS     
bef0: 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23              25.#
bf00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf10: 4e 54 4c 5f 4f 54 41 20 20 20 20 20 20 20 20 20  NTL_OTA         
bf20: 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 0a 2f             26../
bf30: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
bf40: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
bf50: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
bf60: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
bf70: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
bf80: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
bf90: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
bfa0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
bfb0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
bfc0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
bfd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
bfe0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
bff0: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
c000: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
c010: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c020: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
c030: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
c040: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
c050: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
c060: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
c070: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
c080: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
c090: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
c0a0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
c0b0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
c0c0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
c0d0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
c0e0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
c0f0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
c100: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
c110: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
c120: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
c130: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
c140: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
c150: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
c160: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
c170: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c180: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
c190: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
c1a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
c1b0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
c1c0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c1d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
c1e0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
c1f0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
c200: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
c210: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
c220: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
c230: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
c240: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
c250: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
c260: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
c270: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
c280: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
c290: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
c2a0: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
c2b0: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
c2c0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
c2d0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
c2e0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
c2f0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
c300: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
c310: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
c320: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
c330: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
c340: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
c350: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
c360: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
c370: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
c380: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
c390: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
c3a0: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
c3b0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
c3c0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
c3d0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
c3e0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
c3f0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
c400: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
c410: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
c420: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
c430: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
c440: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
c450: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
c460: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
c470: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
c480: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
c490: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
c4a0: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
c4b0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
c4c0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
c4d0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
c4e0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
c4f0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
c500: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
c510: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
c520: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
c530: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
c540: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
c550: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
c560: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
c570: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
c580: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
c590: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
c5a0: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
c5b0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
c5c0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
c5d0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
c5e0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
c5f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
c600: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
c610: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
c620: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
c630: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
c640: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
c650: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
c660: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
c670: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
c680: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
c690: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
c6a0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
c6b0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
c6c0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
c6d0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
c6e0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
c6f0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
c700: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
c710: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
c720: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
c730: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
c740: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
c750: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
c760: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
c770: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
c780: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
c790: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
c7a0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
c7b0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
c7c0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
c7d0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
c7e0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
c7f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
c800: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
c810: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
c820: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c830: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
c840: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
c850: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
c860: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
c870: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
c880: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
c890: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
c8a0: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
c8b0: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
c8c0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c8d0: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
c8e0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
c8f0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
c900: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
c910: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
c920: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
c930: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
c940: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
c950: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
c960: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
c970: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
c980: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
c990: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
c9a0: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
c9b0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
c9c0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
c9d0: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
c9e0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
c9f0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
ca00: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
ca10: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
ca20: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
ca30: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
ca40: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
ca50: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
ca60: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
ca70: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
ca80: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
ca90: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
caa0: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
cab0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
cac0: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
cad0: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
cae0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
caf0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
cb00: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
cb10: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
cb20: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
cb30: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cb40: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
cb50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
cb60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
cb70: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
cb80: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
cb90: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
cba0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
cbb0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
cbc0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
cbd0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
cbe0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
cbf0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
cc00: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
cc10: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
cc20: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
cc30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
cc40: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
cc50: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
cc60: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
cc70: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
cc80: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
cc90: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
cca0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
ccb0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
ccc0: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
ccd0: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
cce0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
ccf0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
cd00: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
cd10: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
cd20: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
cd30: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
cd40: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
cd50: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
cd60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
cd70: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cd80: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
cd90: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
cda0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
cdb0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
cdc0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
cdd0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
cde0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
cdf0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
ce00: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ce10: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
ce20: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ce30: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
ce40: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
ce50: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
ce60: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
ce70: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
ce80: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
ce90: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
cea0: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
ceb0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
cec0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
ced0: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
cee0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
cef0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
cf00: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
cf10: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
cf20: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
cf30: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
cf40: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
cf50: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
cf60: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
cf70: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
cf80: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
cf90: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
cfa0: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
cfb0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
cfc0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
cfd0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
cfe0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
cff0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
d000: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
d010: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
d020: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
d030: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
d040: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
d050: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
d060: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
d070: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
d080: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
d090: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
d0a0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
d0b0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
d0c0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d0d0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
d0e0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d0f0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
d100: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
d110: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
d120: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
d130: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d140: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
d150: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
d160: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
d170: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
d180: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
d190: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d1a0: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
d1b0: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
d1c0: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
d1d0: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
d1e0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
d1f0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
d200: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
d210: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d220: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
d230: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
d240: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
d250: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
d260: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
d270: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
d280: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
d290: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
d2a0: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
d2b0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
d2c0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
d2d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
d2e0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
d2f0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
d300: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
d310: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
d320: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
d330: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
d340: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
d350: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
d360: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
d370: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
d380: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
d390: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
d3a0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
d3b0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
d3c0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
d3d0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
d3e0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
d3f0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
d400: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
d410: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
d420: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
d430: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
d440: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
d450: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
d460: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
d470: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
d480: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
d490: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
d4a0: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
d4b0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
d4c0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
d4d0: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
d4e0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
d4f0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
d500: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
d510: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
d520: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
d530: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
d540: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
d550: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
d560: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
d570: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
d580: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
d590: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d5a0: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
d5b0: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
d5c0: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
d5d0: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
d5e0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
d5f0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
d600: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
d610: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
d620: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
d630: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
d640: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
d650: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
d660: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
d670: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
d680: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
d690: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
d6a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d6b0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
d6c0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
d6d0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
d6e0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
d6f0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d700: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
d710: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
d720: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
d730: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
d740: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
d750: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
d760: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
d770: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
d780: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
d790: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
d7a0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
d7b0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
d7c0: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
d7d0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d7e0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
d7f0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
d800: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
d810: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
d820: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d830: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
d840: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
d850: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
d860: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
d870: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
d880: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
d890: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
d8a0: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
d8b0: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
d8c0: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
d8d0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
d8e0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
d8f0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
d900: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
d910: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
d920: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
d930: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
d940: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d950: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
d960: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
d970: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
d980: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
d990: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
d9a0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
d9b0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
d9c0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
d9d0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d9e0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
d9f0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
da00: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
da10: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
da20: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
da30: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
da40: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
da50: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
da60: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
da70: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
da80: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
da90: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
daa0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
dab0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
dac0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
dad0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
dae0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
daf0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
db00: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
db10: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
db20: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
db30: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
db40: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
db50: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
db60: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
db70: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
db80: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
db90: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
dba0: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
dbb0: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
dbc0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
dbd0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
dbe0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
dbf0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
dc00: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
dc10: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
dc20: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
dc30: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
dc40: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
dc50: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
dc60: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
dc70: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
dc80: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
dc90: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
dca0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
dcb0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
dcc0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
dcd0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
dce0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
dcf0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
dd00: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
dd10: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
dd20: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
dd30: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
dd40: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
dd50: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
dd60: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
dd70: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
dd80: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
dd90: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
dda0: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
ddb0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
ddc0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
ddd0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
dde0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
ddf0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
de00: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
de10: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
de20: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
de30: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
de40: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
de50: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
de60: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
de70: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
de80: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
de90: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
dea0: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
deb0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
dec0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
ded0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
dee0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
def0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
df00: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
df10: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
df20: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
df30: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
df40: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
df50: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
df60: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
df70: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
df80: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
df90: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
dfa0: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
dfb0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
dfc0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
dfd0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
dfe0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
dff0: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
e000: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
e010: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
e020: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
e030: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
e040: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
e050: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
e060: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
e070: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
e080: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
e090: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e0a0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
e0b0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
e0c0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
e0d0: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
e0e0: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
e0f0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
e100: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
e110: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
e120: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
e130: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
e140: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
e150: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
e160: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
e170: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
e180: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
e190: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
e1a0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
e1b0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
e1c0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
e1d0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
e1e0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
e1f0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
e200: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
e210: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
e220: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
e230: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
e240: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e250: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e260: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
e270: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
e280: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
e290: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
e2a0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e2b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e2c0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
e2d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
e2e0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
e2f0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e300: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
e310: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
e320: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
e330: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
e340: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e350: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
e360: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
e370: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
e380: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e390: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
e3a0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
e3b0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
e3c0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
e3d0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
e3e0: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
e3f0: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
e400: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
e410: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
e420: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
e430: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
e440: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
e450: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
e460: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
e470: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
e480: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
e490: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
e4a0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
e4b0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
e4c0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
e4d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
e4e0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
e4f0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
e500: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e510: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
e520: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e530: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e540: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
e550: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e560: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
e570: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
e580: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
e590: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
e5a0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
e5b0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
e5c0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
e5d0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
e5e0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
e5f0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e600: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e610: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
e620: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
e630: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
e640: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
e650: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
e660: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
e670: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
e680: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e690: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e6a0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
e6b0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
e6c0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
e6d0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
e6e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e6f0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
e700: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
e710: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
e720: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e730: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e740: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
e750: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e760: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e770: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
e780: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e790: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
e7a0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
e7b0: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
e7c0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
e7d0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
e7e0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
e7f0: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
e800: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
e810: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e820: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
e830: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
e840: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
e850: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
e860: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
e870: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
e880: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
e890: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
e8a0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
e8b0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
e8c0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
e8d0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
e8e0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
e8f0: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
e900: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
e910: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
e920: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
e930: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
e940: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
e950: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
e960: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
e970: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
e980: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
e990: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
e9a0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
e9b0: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
e9c0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
e9d0: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
e9e0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
e9f0: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
ea00: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
ea10: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
ea20: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
ea30: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
ea40: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
ea50: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
ea60: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
ea70: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
ea80: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ea90: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
eaa0: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
eab0: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
eac0: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
ead0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
eae0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
eaf0: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
eb00: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
eb10: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
eb20: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
eb30: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
eb40: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
eb50: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
eb60: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
eb70: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
eb80: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
eb90: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
eba0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
ebb0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
ebc0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
ebd0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ebe0: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
ebf0: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
ec00: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
ec10: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
ec20: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ec30: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
ec40: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
ec50: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
ec60: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
ec70: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
ec80: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
ec90: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
eca0: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
ecb0: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
ecc0: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
ecd0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
ece0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
ecf0: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
ed00: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
ed10: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
ed20: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
ed30: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
ed40: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
ed50: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
ed60: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
ed70: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ed80: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
ed90: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
eda0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
edb0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
edc0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
edd0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
ede0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
edf0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
ee00: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
ee10: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
ee20: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
ee30: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
ee40: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
ee50: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
ee60: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
ee70: 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
ee80: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
ee90: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
eea0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
eeb0: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
eec0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
eed0: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
eee0: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
eef0: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
ef00: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
ef10: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
ef20: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
ef30: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
ef40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
ef50: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
ef60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ef70: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
ef80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ef90: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
efa0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
efb0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
efc0: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
efd0: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
efe0: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
eff0: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
f000: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
f010: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
f020: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
f030: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
f040: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
f050: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
f060: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
f070: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
f080: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
f090: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
f0a0: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
f0b0: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
f0c0: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
f0d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
f0e0: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
f0f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
f100: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
f110: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
f120: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f130: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f140: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
f150: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
f160: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
f170: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
f180: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
f190: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
f1a0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
f1b0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
f1c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
f1d0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
f1e0: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
f1f0: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
f200: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f210: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
f220: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
f230: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
f240: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
f250: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
f260: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
f270: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
f280: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
f290: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
f2a0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f2b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f2c0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
f2d0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
f2e0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
f2f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f300: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
f310: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
f320: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
f330: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
f340: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
f350: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f360: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f370: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
f380: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f390: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
f3a0: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
f3b0: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
f3c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f3d0: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
f3e0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
f3f0: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
f400: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
f410: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
f420: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f430: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
f440: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
f450: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
f460: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
f470: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f480: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
f490: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f4a0: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
f4b0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
f4c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
f4d0: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
f4e0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
f4f0: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
f500: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
f510: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f520: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
f530: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
f540: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
f550: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
f560: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
f570: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
f580: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
f590: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
f5a0: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
f5b0: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
f5c0: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
f5d0: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
f5e0: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
f5f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f600: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
f610: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
f620: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
f630: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
f640: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
f650: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
f660: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
f670: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
f680: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
f690: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f6a0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
f6b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f6c0: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
f6d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f6e0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
f6f0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f700: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
f710: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f720: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
f730: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
f740: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
f750: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
f760: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
f770: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
f780: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
f790: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
f7a0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
f7b0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
f7c0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
f7d0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
f7e0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
f7f0: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
f800: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
f810: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
f820: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
f830: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
f840: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
f850: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
f860: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
f870: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
f880: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
f890: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
f8a0: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
f8b0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
f8c0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
f8d0: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
f8e0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
f8f0: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
f900: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f910: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
f920: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
f930: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
f940: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
f950: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f960: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
f970: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
f980: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
f990: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
f9a0: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
f9b0: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
f9c0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
f9d0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
f9e0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
f9f0: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
fa00: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
fa10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
fa20: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
fa30: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
fa40: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
fa50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa60: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
fa70: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
fa80: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
fa90: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
faa0: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
fab0: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
fac0: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
fad0: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
fae0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
faf0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
fb00: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
fb10: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
fb20: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fb30: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
fb40: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
fb50: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
fb60: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
fb70: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
fb80: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
fb90: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
fba0: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
fbb0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
fbc0: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
fbd0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
fbe0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
fbf0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
fc00: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
fc10: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
fc20: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
fc30: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
fc40: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
fc50: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
fc60: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
fc70: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
fc80: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
fc90: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
fca0: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
fcb0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
fcc0: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
fcd0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
fce0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
fcf0: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
fd00: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
fd10: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
fd20: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
fd30: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
fd40: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
fd50: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
fd60: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
fd70: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
fd80: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
fd90: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
fda0: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
fdb0: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
fdc0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
fdd0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
fde0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
fdf0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
fe00: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
fe10: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
fe20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
fe30: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
fe40: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
fe50: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
fe60: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe70: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
fe80: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
fe90: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
fea0: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
feb0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
fec0: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
fed0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
fee0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
fef0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
ff00: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
ff10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
ff20: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
ff30: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
ff40: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
ff50: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
ff60: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
ff70: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
ff80: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
ff90: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
ffa0: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
ffb0: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
ffc0: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
ffd0: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
ffe0: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
fff0: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
10000 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
10010 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
10020 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
10030 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
10040 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10050 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
10060 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
10070 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
10080 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10090 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
100a0 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
100b0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
100c0 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
100d0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
100e0 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
100f0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
10100 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
10110 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
10120 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
10130 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
10140 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
10150 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10160 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
10170 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
10180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10190 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
101a0 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
101b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
101c0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
101d0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
101e0 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
101f0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
10200 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
10210 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
10220 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
10230 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
10240 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
10250 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
10260 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
10270 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
10280 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
10290 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
102a0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
102b0 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
102c0 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
102d0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
102e0 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
102f0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
10300 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
10310 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10320 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10330 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
10340 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
10350 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72  on.** must insur
10360 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
10370 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10380 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
10390 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
103a0 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
103b0 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
103c0 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  ing.  Furthermor
103d0 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e, sqlite3_confi
103e0 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  g().** may only 
103f0 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
10400 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
10410 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
10420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
10430 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
10440 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
10450 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10460 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
10470 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
10480 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
10490 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
104a0 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
104b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
104c0 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
104d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
104e0 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
104f0 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
10500 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
10510 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
10520 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
10530 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
10540 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
10550 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
10560 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
10570 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
10580 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
10590 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
105a0 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
105b0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
105c0 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
105d0 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
105e0 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
105f0 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
10600 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
10610 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
10620 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
10630 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
10640 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
10650 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
10660 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
10670 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
10680 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
10690 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
106a0 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
106b0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
106c0 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
106d0 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
106e0 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
106f0 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
10700 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
10710 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
10720 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
10730 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10740 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
10750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10760 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
10770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10780 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
10790 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
107a0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
107b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
107c0 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
107d0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
107e0 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
107f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10800 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
10810 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
10820 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10830 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
10840 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
10850 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
10860 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10870 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
10880 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
10890 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
108a0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
108b0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
108c0 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
108d0 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
108e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
108f0 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
10900 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
10910 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
10920 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
10930 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
10940 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
10950 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
10960 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
10970 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
10980 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
10990 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
109a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
109b0 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
109c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
109d0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
109e0 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
109f0 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
10a00 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
10a10 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
10a20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
10a30 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
10a40 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
10a50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10a60 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
10a70 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
10a80 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
10a90 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
10aa0 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
10ab0 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
10ac0 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
10ad0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
10ae0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
10af0 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
10b00 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
10b10 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
10b20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10b30 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
10b40 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
10b50 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
10b60 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
10b70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10b80 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
10b90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10ba0 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
10bb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10bc0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
10bd0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
10be0 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
10bf0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10c00 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
10c10 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
10c20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10c30 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
10c40 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
10c50 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
10c60 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
10c70 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
10c80 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10c90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10ca0 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
10cb0 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
10cc0 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
10cd0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
10ce0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
10cf0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
10d00 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
10d10 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
10d20 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
10d30 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
10d40 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
10d50 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
10d60 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
10d70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
10d80 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
10d90 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
10da0 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
10db0 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
10dc0 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
10dd0 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
10de0 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
10df0 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
10e00 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
10e10 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
10e20 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
10e30 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
10e40 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
10e50 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
10e60 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
10e70 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
10e80 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
10e90 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
10ea0 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
10eb0 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
10ec0 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
10ed0 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
10ee0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
10ef0 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
10f00 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
10f10 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
10f20 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
10f30 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10f40 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10f50 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10f60 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10f70 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10f80 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10f90 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10fa0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10fb0 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10fc0 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10fd0 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
10fe0 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
10ff0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
11000 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11010 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
11020 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
11030 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
11040 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
11050 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
11060 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
11070 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
11080 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
11090 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
110a0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
110b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
110c0 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
110d0 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
110e0 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
110f0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
11100 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11110 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
11120 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
11130 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
11140 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
11150 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
11160 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
11170 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
11180 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
11190 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
111a0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
111b0 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
111c0 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
111d0 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
111e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
111f0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
11200 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
11210 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
11220 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
11230 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
11240 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
11250 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
11260 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
11270 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
11280 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
11290 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
112a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
112b0 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
112c0 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
112d0 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
112e0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
112f0 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
11300 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
11310 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
11320 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
11330 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
11340 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
11350 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
11360 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
11370 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
11380 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
11390 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
113a0 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
113b0 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
113c0 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
113d0 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
113e0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
113f0 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
11400 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
11410 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
11420 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
11430 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
11440 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
11450 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
11460 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
11470 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
11480 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
11490 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
114a0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
114b0 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
114c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
114d0 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
114e0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
114f0 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
11500 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
11510 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
11520 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
11530 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
11540 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
11550 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
11560 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
11570 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11580 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
11590 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
115a0 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
115b0 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
115c0 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
115d0 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
115e0 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
115f0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
11600 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11610 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
11620 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
11630 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
11640 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
11650 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
11660 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
11670 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
11680 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
11690 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
116a0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
116b0 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
116c0 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
116d0 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
116e0 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
116f0 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
11700 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11710 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
11720 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
11730 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11740 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
11750 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
11760 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
11770 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
11780 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
11790 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
117a0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
117b0 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
117c0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
117d0 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
117e0 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
117f0 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
11800 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11810 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
11820 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
11830 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
11840 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
11850 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
11860 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
11870 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
11880 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
11890 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
118a0 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
118b0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
118c0 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
118d0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
118e0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
118f0 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
11900 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
11910 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
11920 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
11930 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
11940 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
11950 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
11960 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
11970 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
11980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11990 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
119a0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
119b0 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
119c0 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
119d0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
119e0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
119f0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
11a00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11a10 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
11a20 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
11a30 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
11a40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
11a50 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
11a60 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
11a70 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11a80 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
11a90 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
11aa0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
11ab0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
11ac0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
11ad0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
11ae0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
11af0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
11b00 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
11b10 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
11b20 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
11b30 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
11b40 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
11b50 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
11b60 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11b70 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
11b80 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
11b90 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
11ba0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
11bb0 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
11bc0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
11bd0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
11be0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
11bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11c00 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
11c10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11c20 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
11c30 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11c40 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11c50 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11c60 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11c70 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11c80 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
11c90 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
11ca0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11cb0 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
11cc0 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
11cd0 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
11ce0 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
11cf0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
11d00 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
11d10 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
11d20 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11d30 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11d40 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11d50 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11d60 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11d70 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11d80 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11d90 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
11da0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11db0 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
11dc0 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
11dd0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
11de0 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
11df0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11e00 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
11e10 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11e20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11e30 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
11e40 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
11e50 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11e60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11e70 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11e80 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
11e90 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11ea0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
11eb0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11ec0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11ed0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11ee0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11ef0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11f00 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
11f10 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
11f20 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11f30 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
11f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11f50 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11f60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11f70 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
11f80 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
11f90 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
11fa0 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
11fb0 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
11fc0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
11fd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11fe0 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
11ff0 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
12000 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
12010 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
12020 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
12030 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
12040 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
12050 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
12060 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
12070 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
12080 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
12090 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
120a0 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
120b0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
120c0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
120d0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
120e0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
120f0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
12100 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12110 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
12120 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
12130 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
12140 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
12150 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12160 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12170 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12180 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12190 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
121a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
121b0 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
121c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
121d0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
121e0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
121f0 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
12200 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12210 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
12220 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
12230 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12240 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
12250 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12260 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12270 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
12280 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12290 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
122a0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
122b0 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
122c0 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
122d0 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
122e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
122f0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12300 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
12310 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
12320 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
12330 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
12340 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12350 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
12360 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
12370 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
12380 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
12390 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
123a0 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
123b0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
123c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
123d0 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
123e0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
123f0 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
12400 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
12410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
12420 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
12430 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
12440 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
12450 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
12460 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
12470 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12480 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12490 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
124a0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
124b0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
124c0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
124d0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
124e0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
124f0 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
12500 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12510 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12520 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12530 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12540 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12550 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
12560 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12570 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
12580 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12590 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
125a0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
125b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
125c0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
125d0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
125e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70  CONFIG_MALLOC op
125f0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12600 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12610 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  ch is .** a poin
12620 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
12630 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12640 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12650 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
12660 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
12670 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
12680 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
12690 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
126a0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
126b0 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
126c0 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
126d0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
126e0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
126f0 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
12700 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
12710 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
12720 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
12730 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12740 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12750 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
12760 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12770 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
12780 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12790 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
127a0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
127b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
127c0 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
127d0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
127e0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
127f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12800 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12810 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
12820 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12830 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12840 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12850 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
12860 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12870 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
12880 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
12890 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
128a0 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
128b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
128c0 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
128d0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
128e0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
128f0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
12900 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
12910 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
12920 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
12930 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
12940 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
12950 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
12960 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
12970 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
12980 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12990 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
129a0 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
129b0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
129c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
129d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
129e0 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e  MEMSTATUS option
129f0 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
12a00 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
12a10 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  nt,.** interpret
12a20 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c  ed as a boolean,
12a30 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
12a40 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
12a50 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20  ollection of.** 
12a60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12a70 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  n statistics. ^(
12a80 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
12a90 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12aa0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
12ab0 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  d, the following
12ac0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12ad0 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
12ae0 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
12af0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
12b00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
12b10 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
12b20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
12b30 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
12b40 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12b50 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
12b60 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
12b70 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36  [sqlite3_status6
12b80 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  4()].**   </ul>)
12b90 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
12ba0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12bb0 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
12bc0 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
12bd0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
12be0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
12bf0 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
12c00 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
12c10 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
12c20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
12c30 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
12c40 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
12c50 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
12c60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
12c70 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
12c80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12c90 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
12ca0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12cb0 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f  IG_SCRATCH optio
12cc0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12cd0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12ce0 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  er.** that SQLit
12cf0 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63  e can use for sc
12d00 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e  ratch memory.  ^
12d10 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  (There are three
12d20 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f   arguments.** to
12d30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12d40 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74  CRATCH:  A point
12d50 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
12d60 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
12d70 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
12d80 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
12d90 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
12da0 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
12db0 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
12dc0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
12dd0 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
12de0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
12df0 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
12e00 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20  tions (N).)^.** 
12e10 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12e20 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
12e30 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
12e40 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
12e50 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
12e60 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
12e70 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
12e80 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f   will not use mo
12e90 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61  re than one scra
12ea0 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
12eb0 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69  thread..** ^SQLi
12ec0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
12ed0 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20  quest a scratch 
12ee0 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
12ef0 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
12f00 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
12f10 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e   page size..** ^
12f20 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
12f30 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
12f40 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
12f50 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
12f60 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
12f70 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
12f80 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
12f90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
12fa0 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
12fb0 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
12fc0 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70  memory needed.<p
12fd0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61  >.** ^When the a
12fe0 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69  pplication provi
12ff0 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f  des any amount o
13000 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  f scratch memory
13010 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45   using.** SQLITE
13020 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c  _CONFIG_SCRATCH,
13030 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75   SQLite avoids u
13040 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65  nnecessary large
13050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
13060 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74  loc|heap allocat
13070 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63  ions]..** This c
13080 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20  an help [Robson 
13090 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65  proof|prevent me
130a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
130b0 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f  failures] due to
130c0 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e   heap.** fragmen
130d0 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65  tation in low-me
130e0 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79  mory embedded sy
130f0 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  stems..** </dd>.
13100 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13110 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
13120 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13130 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
13140 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13160 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73  GECACHE option s
13170 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
13180 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a  c memory buffer.
13190 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
131a0 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64  an use for the d
131b0 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
131c0 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
131d0 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ult page.** cach
131e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
131f0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
13200 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
13210 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
13220 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
13230 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
13240 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13250 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
13260 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
13270 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a 2a  ONFIG_PCACHE2].*
13280 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
13290 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72  option..** ^Ther
132a0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
132b0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
132c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
132d0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  : A pointer to.*
132e0 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  * 8-byte aligned
132f0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
13300 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
13310 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
13320 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
13330 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
13340 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
13350 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
13360 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
13370 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
13380 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
13390 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
133a0 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f  d 65536) plus so
133b0 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66  me extra bytes f
133c0 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
133d0 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75  header.  ^The nu
133e0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79  mber of extra by
133f0 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68  tes needed by th
13400 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a  e page header.**
13410 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
13420 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ed using the [SQ
13430 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13440 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f 6e  HE_HDRSZ] option
13450 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33   .** to [sqlite3
13460 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e  _config()]..** ^
13470 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
13480 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
13490 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
134a0 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
134b0 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
134c0 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
134d0 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  y.  The first.**
134e0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
134f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
13500 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 6c  -byte aligned bl
13510 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68  ock of memory th
13520 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61 73  at.** is at leas
13530 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
13540 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69 73  memory, otherwis
13550 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  e subsequent beh
13560 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
13570 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  fined..** ^SQLit
13580 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
13590 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
135a0 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
135b0 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
135c0 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
135d0 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
135e0 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
135f0 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
13600 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
13610 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
13620 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
13630 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
13640 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
13650 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
13660 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
13670 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13680 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
13690 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
136a0 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ce.</dd>.**.** [
136b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
136c0 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
136d0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
136e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
136f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13700 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  P option specifi
13710 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
13720 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68  ry buffer .** th
13730 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
13740 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
13750 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
13760 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
13770 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73  s.** beyond thos
13780 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62  e provided for b
13790 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
137a0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a  _SCRATCH] and.**
137b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
137c0 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e  PAGECACHE]..** ^
137d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
137e0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73  G_HEAP option is
137f0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
13800 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
13810 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69  piled.** with ei
13820 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
13830 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20  BLE_MEMSYS3] or 
13840 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13850 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75  EMSYS5] and retu
13860 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rns.** [SQLITE_E
13870 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64  RROR] if invoked
13880 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e   otherwise..** ^
13890 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
138a0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
138b0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a  ITE_CONFIG_HEAP:
138c0 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  .** An 8-byte al
138d0 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
138e0 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
138f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
13900 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
13910 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
13920 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13930 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
13940 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
13950 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
13960 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
13970 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
13980 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
13990 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
139a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
139b0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
139c0 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
139d0 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
139e0 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
139f0 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
13a00 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
13a10 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
13a20 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
13a30 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  t NULL then the 
13a40 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
13a50 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
13a60 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
13a70 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
13a80 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
13a90 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
13aa0 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
13ab0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
13ac0 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
13ad0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
13ae0 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
13af0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
13b00 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
13b10 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
13b20 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
13b30 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
13b40 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
13b50 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
13b60 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
13b70 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
13b80 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
13b90 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
13ba0 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
13bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13bc0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
13bd0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
13be0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13bf0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13c00 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
13c10 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13c20 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a  ent which is a.*
13c30 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
13c40 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
13c50 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
13c60 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13c70 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
13c80 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74  nt specifies alt
13c90 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
13ca0 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
13cb0 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20  s to be used.** 
13cc0 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74  in place the mut
13cd0 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
13ce0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
13cf0 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
13d00 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
13d10 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
13d20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
13d30 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13d40 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
13d50 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
13d60 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
13d70 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
13d80 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13d90 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13da0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13db0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13dc0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13dd0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
13de0 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
13df0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
13e00 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
13e10 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
13e20 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
13e30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
13e40 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
13e50 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
13e60 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
13e70 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
13e80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
13e90 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13ea0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
13eb0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
13ec0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
13ed0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13ee0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13ef0 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e  _GETMUTEX option
13f00 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13f10 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
13f20 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
13f30 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
13f40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
13f50 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
13f60 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
13f70 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
13f80 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
13f90 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
13fa0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
13fb0 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
13fc0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13fd0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13fe0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13ff0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
14000 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
14010 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
14020 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
14030 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
14040 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
14050 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
14060 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
14070 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
14080 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14090 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
140a0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
140b0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
140c0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
140d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
140e0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
140f0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
14100 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
14110 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
14120 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
14130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
14140 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
14150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14160 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
14170 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
14180 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
14190 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
141a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
141b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
141c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
141d0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
141e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
141f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14200 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20  OOKASIDE option 
14210 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
14220 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
14230 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  ne.** the defaul
14240 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73  t size of lookas
14250 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61  ide memory on ea
14260 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ch [database con
14270 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
14280 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14290 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
142a0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
142b0 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
142c0 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
142d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
142e0 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
142f0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
14300 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
14310 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ^(SQLITE_CONFIG_
14320 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74  LOOKASIDE.** set
14330 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74  s the <i>default
14340 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
14350 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
14360 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
14370 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74  IDE].** option t
14380 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
14390 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
143a0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
143b0 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
143c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
143d0 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
143e0 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
143f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14400 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
14410 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14420 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
14430 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14440 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14450 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
14460 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14470 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
14480 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
14490 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
144a0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
144b0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
144c0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69  ecifies.** the i
144d0 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75  nterface to a cu
144e0 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
144f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
14500 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b  ^.** ^SQLite mak
14510 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
14520 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14530 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14540 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  t.</dd>.**.** [[
14550 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14560 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
14570 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14580 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
14590 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
145a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
145b0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
145c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
145d0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
145e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
145f0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14600 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14610 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
14620 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e  of.** the curren
14630 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
14640 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
14650 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
14660 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
14680 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14690 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
146a0 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
146b0 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
146c0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
146d0 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
146e0 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
146f0 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
14700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14710 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
14720 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
14730 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
14740 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
14750 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
14760 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
14770 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
14780 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
14790 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
147a0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
147b0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
147c0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
147d0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
147e0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
147f0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
14800 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
14810 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
14820 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
14830 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
14840 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
14850 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
14860 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
14870 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
14880 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
14890 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
148a0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
148b0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
148c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
148d0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
148e0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
148f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
14900 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
14910 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
14920 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
14930 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
14940 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
14950 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
14960 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14970 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
14980 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
14990 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
149a0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
149b0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
149c0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
149d0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
149e0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
149f0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
14a00 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
14a10 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
14a20 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
14a30 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
14a40 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
14a50 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
14a60 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
14a70 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
14a80 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
14a90 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
14aa0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
14ab0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
14ac0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
14ad0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
14ae0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
14af0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
14b00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
14b10 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
14b20 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
14b30 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
14b40 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14b50 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
14b60 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14b70 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65  URI.** <dd>^(The
14b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
14b90 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  RI option takes 
14ba0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14bb0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a  t of type int..*
14bc0 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  * If non-zero, t
14bd0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
14be0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
14bf0 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
14c00 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a  ameter is zero,.
14c10 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  ** then URI hand
14c20 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
14c30 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
14c40 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14c50 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61   globally.** ena
14c60 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
14c70 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  mes passed to [s
14c80 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
14c90 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
14ca0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
14cb0 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
14cc0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
14cd0 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
14ce0 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
14cf0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
14d00 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
14d10 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
14d20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
14d30 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
14d40 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
14d50 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
14d60 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
14d70 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
14d80 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
14d90 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
14da0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
14db0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
14dc0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
14dd0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
14de0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
14df0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
14e00 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
14e10 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14e20 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
14e30 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
14e40 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
14e50 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
14e60 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
14e70 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
14e80 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
14e90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
14ea0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14eb0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
14ec0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14ed0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14ee0 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
14ef0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14f00 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14f10 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  CAN option takes
14f20 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
14f30 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68  r.** argument wh
14f40 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
14f50 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  ed as a boolean 
14f60 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
14f70 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a  le or disable.**
14f80 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
14f90 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
14fa0 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14fb0 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
14fc0 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68  ptimizer..** ^Th
14fd0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
14fe0 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
14ff0 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
15000 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
15010 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
15020 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15030 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
15040 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
15050 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
15060 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
15070 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
15080 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
15090 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
150a0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
150b0 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
150c0 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
150d0 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
150e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
150f0 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
15100 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
15110 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
15120 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
15130 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
15140 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
15150 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
15160 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
15170 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
15180 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
15190 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
151a0 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
151b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
151c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
151d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
151e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
151f0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
15200 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15210 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
15220 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15230 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
15240 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
15250 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
15260 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
15270 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
15280 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
15290 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
152a0 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
152b0 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
152c0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
152d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
152e0 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
152f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15300 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
15310 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
15320 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
15330 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15340 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
15350 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
15360 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15370 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
15380 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15390 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
153a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
153b0 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
153c0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
153d0 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
153e0 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
153f0 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
15400 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
15410 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
15420 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
15430 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
15440 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
15450 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
15460 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
15470 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
15480 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
15490 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
154a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
154b0 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
154c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
154d0 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
154e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
154f0 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
15500 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
15510 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
15520 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
15530 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
15540 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
15550 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
15560 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
15570 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
15580 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
15590 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
155a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
155b0 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
155c0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
155d0 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
155e0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
155f0 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
15600 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
15610 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
15620 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15630 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
15640 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
15650 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
15660 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
15670 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
15680 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
15690 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
156a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
156b0 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
156c0 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
156d0 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
156e0 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
156f0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
15700 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
15710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
15720 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
15730 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
15740 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
15750 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
15760 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
15770 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
15780 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
15790 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
157a0 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
157b0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
157c0 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
157d0 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
157e0 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
157f0 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
15800 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
15810 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
15820 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
15830 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
15840 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
15850 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15860 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
15870 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
15880 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
15890 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
158a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
158b0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
158c0 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
158d0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
158e0 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69   mmap size.** wi
158f0 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74  ll be silently t
15900 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65  runcated if nece
15910 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74  ssary so that it
15920 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64   does not exceed
15930 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d   the.** compile-
15940 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
15950 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
15960 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
15970 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
15980 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
15990 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
159a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
159b0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
159c0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
159d0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
159e0 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
159f0 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
15a00 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  lt..**.** [[SQLI
15a10 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15a20 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  HEAPSIZE]].** <d
15a30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15a40 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a  WIN32_HEAPSIZE.*
15a50 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
15a60 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
15a70 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69  EAPSIZE option i
15a80 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
15a90 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a   if SQLite is.**
15aa0 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69   compiled for Wi
15ab0 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b  ndows with the [
15ac0 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
15ad0 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOC] pre-process
15ae0 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69  or macro.** defi
15af0 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e  ned. ^SQLITE_CON
15b00 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15b10 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69  ZE takes a 32-bi
15b20 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
15b30 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74  er value.** that
15b40 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d   specifies the m
15b50 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74  aximum size of t
15b60 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e  he created heap.
15b70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15b80 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
15b90 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  RSZ]].** <dt>SQL
15ba0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15bb0 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  E_HDRSZ.** <dd>^
15bc0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15bd0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f  G_PCACHE_HDRSZ o
15be0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15bf0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
15c00 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
15c10 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
15c20 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  er and writes in
15c30 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
15c40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
15c50 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72  tra.** bytes per
15c60 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66   page required f
15c70 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20  or each page in 
15c80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15c90 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
15ca0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72  e amount of extr
15cb0 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  a space required
15cc0 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65   can change depe
15cd0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d  nding on the com
15ce0 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74  piler,.** target
15cf0 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53   platform, and S
15d00 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a  QLite version..*
15d10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15d20 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20  NFIG_PMASZ]].** 
15d30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15d40 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  G_PMASZ.** <dd>^
15d50 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15d60 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74  G_PMASZ option t
15d70 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
15d80 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
15d90 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
15da0 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73  integer and sets
15db0 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d   the "Minimum PM
15dc0 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20  A Size" for the 
15dd0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a  multithreaded.**
15de0 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20   sorter to that 
15df0 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65  integer.  The de
15e00 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d  fault minimum PM
15e10 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79  A Size is set by
15e20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15e30 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f  SORTER_PMASZ] co
15e40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15e50 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20  n.  New threads 
15e60 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20  are launched.** 
15e70 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72  to help with sor
15e80 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65  t operations whe
15e90 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  n multithreaded 
15ea0 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e  sorting.** is en
15eb0 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65  abled (using the
15ec0 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73   [PRAGMA threads
15ed0 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74  ] command) and t
15ee0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  he amount of con
15ef0 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f  tent.** to be so
15f00 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65  rted exceeds the
15f10 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73   page size times
15f20 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20   the minimum of 
15f30 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63  the.** [PRAGMA c
15f40 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69  ache_size] setti
15f50 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75  ng and this valu
15f60 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  e..** </dl>.*/.#
15f70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15f80 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
15f90 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
15fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15fb0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
15fc0 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
15fd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15fe0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
15ff0 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
16000 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16010 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
16020 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
16030 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
16040 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16050 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
16060 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
16070 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16080 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
160a0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
160b0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
160c0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
160d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
160e0 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
160f0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16100 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16110 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16120 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
16130 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
16140 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
16150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16160 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
16170 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
16180 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
16190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
161a0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
161b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
161c0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
161d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
161e0 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
161f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16200 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
16210 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
16220 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
16230 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
16240 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
16250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16260 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16270 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
16280 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
16290 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
162a0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
162b0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
162c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
162d0 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
162e0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
162f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16300 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
16310 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
16320 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
16330 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
16340 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
16350 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16360 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16370 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
16380 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16390 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
163a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
163b0 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
163c0 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
163d0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
163e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
163f0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16400 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
16410 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
16420 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16430 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
16440 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
16450 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
16460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16470 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
16480 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
16490 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
164a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
164b0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
164c0 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
164d0 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
164e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
164f0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16500 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
16510 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
16520 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16530 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
16540 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
16550 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
16560 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
16570 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
16580 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
16590 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
165a0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
165b0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
165c0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
165d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
165e0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
165f0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
16600 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16610 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
16620 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
16630 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
16640 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
16650 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
16660 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
16670 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
16680 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
16690 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
166a0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
166b0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
166c0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
166d0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
166e0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
166f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16700 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
16710 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
16720 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
16730 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
16740 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
16750 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
16760 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
16770 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
16780 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
16790 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
167a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
167b0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
167c0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
167d0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
167e0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
167f0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
16800 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
16810 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
16820 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
16830 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
16840 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
16850 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
16860 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
16870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16880 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
16890 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
168a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
168b0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
168c0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
168d0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
168e0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
168f0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
16900 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
16910 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16920 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
16930 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16940 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
16950 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
16960 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
16970 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
16980 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
16990 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
169a0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
169b0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
169c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
169d0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
169e0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
169f0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
16a00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
16a10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16a20 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
16a30 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
16a40 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16a50 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
16a60 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
16a70 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
16a80 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
16a90 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
16aa0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
16ab0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
16ac0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
16ad0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
16ae0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
16af0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
16b00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16b10 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
16b20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
16b30 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
16b40 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
16b50 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
16b60 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
16b70 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
16b80 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
16b90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
16ba0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
16bb0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
16bc0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
16bd0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
16be0 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
16bf0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
16c00 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
16c10 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
16c20 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
16c30 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
16c40 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
16c50 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
16c60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
16c70 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
16c80 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
16c90 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
16ca0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
16cb0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
16cc0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
16cd0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
16ce0 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
16cf0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
16d00 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
16d10 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
16d20 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
16d30 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16d40 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16d50 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
16d60 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16d70 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
16d80 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
16d90 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
16da0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
16db0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
16dc0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
16dd0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
16de0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
16df0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
16e00 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
16e10 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
16e20 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
16e30 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
16e40 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
16e50 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
16e60 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
16e70 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
16e80 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
16e90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16ea0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16eb0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
16ec0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
16ed0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
16ee0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
16ef0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
16f00 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
16f10 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
16f20 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
16f30 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
16f40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
16f50 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
16f60 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
16f70 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
16f80 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
16f90 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
16fa0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16fb0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
16fc0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
16fd0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
16fe0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
16ff0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
17000 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17010 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
17020 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17030 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17040 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17050 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17060 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17070 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
17080 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
17090 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
170a0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
170b0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
170c0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
170d0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
170e0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
170f0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
17100 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
17110 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
17120 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
17130 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
17140 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
17150 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
17160 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
17170 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
17180 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
17190 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
171a0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
171b0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
171c0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
171d0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
171e0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
171f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
17200 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
17210 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
17220 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
17230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17240 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
17250 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
17260 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
17270 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
17280 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
17290 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
172a0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
172b0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
172c0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
172d0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
172e0 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
172f0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
17300 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
17310 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
17320 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
17330 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
17340 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
17350 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
17360 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
17370 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
17380 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
17390 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
173a0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
173b0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
173c0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
173d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
173e0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
173f0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
17400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17410 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
17420 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
17430 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
17440 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
17450 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
17460 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
17470 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
17480 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
17490 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
174a0 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
174b0 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
174c0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
174d0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
174e0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
174f0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
17500 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
17510 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
17520 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
17530 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
17540 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
17550 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
17560 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
17570 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
17580 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
17590 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
175a0 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
175b0 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
175c0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
175d0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
175e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
175f0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17600 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
17610 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
17620 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20  wid] of the .** 
17630 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
17640 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
17650 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62  into a rowid tab
17660 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  le or [virtual t
17670 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61  able].** on data
17680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17690 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69  D..** ^Inserts i
176a0 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
176b0 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
176c0 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20  ot recorded..** 
176d0 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
176e0 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
176f0 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a   rowid tables.**
17700 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
17710 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62  red on the datab
17720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
17730 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  , .** then sqlit
17740 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
17750 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
17760 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  zero..**.** ^(If
17770 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
17780 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
17790 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
177a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
177b0 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
177c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
177d0 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
177e0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
177f0 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
17800 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
17810 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
17820 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
17830 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
17840 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
17850 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
17860 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
17870 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17880 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
17890 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
178a0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
178b0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
178c0 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
178d0 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
178e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
178f0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
17900 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
17910 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
17920 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
17930 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
17940 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
17950 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
17960 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
17970 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
17980 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
17990 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
179a0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
179b0 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
179c0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
179d0 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
179e0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
179f0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
17a00 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
17a10 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
17a20 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
17a30 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
17a40 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
17a50 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
17a60 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
17a70 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
17a80 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
17a90 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
17aa0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
17ab0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
17ac0 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
17ad0 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
17ae0 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
17af0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
17b00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
17b10 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
17b20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
17b30 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
17b40 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
17b50 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
17b60 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
17b70 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
17b80 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
17b90 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
17ba0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
17bb0 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
17bc0 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
17bd0 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
17be0 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
17bf0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
17c00 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
17c10 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
17c20 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
17c30 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
17c40 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
17c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
17c60 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
17c70 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
17c80 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
17c90 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
17ca0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
17cb0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
17cc0 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
17cd0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17ce0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
17cf0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
17d00 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
17d10 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
17d20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
17d30 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
17d40 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
17d50 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
17d60 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
17d70 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17d80 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
17d90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17da0 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
17db0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
17dc0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
17dd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
17de0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
17df0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
17e00 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
17e10 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a  , inserted or.**
17e20 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
17e30 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
17e40 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
17e50 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
17e60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  .** statement on
17e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
17e80 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
17e90 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70  ed by the only p
17ea0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78  arameter..** ^Ex
17eb0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
17ec0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
17ed0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
17ee0 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75   modify the valu
17ef0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
17f00 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
17f10 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e  **.** ^Only chan
17f20 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c  ges made directl
17f30 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  y by the INSERT,
17f40 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
17f50 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a  E statement are.
17f60 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20  ** considered - 
17f70 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  auxiliary change
17f80 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45  s caused by [CRE
17f90 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
17fa0 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f  iggers], .** [fo
17fb0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
17fc0 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20  s] or [REPLACE] 
17fd0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
17fe0 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f  ution are not co
17ff0 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68  unted..** .** Ch
18000 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
18010 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
18020 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53  pted by .** [INS
18030 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
18040 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  | INSTEAD OF tri
18050 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63  ggers] are not c
18060 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c  ounted. ^The val
18070 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ue .** returned 
18080 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
18090 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79  es() immediately
180a0 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54   after an INSERT
180b0 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20  , UPDATE or .** 
180c0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
180d0 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69   run on a view i
180e0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f  s always zero. O
180f0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
18100 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62   to real .** tab
18110 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  les are counted.
18120 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72  .**.** Things ar
18130 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
18140 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65  ed if the sqlite
18150 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
18160 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75  tion is.** execu
18170 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67  ted while a trig
18180 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72  ger program is r
18190 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79  unning. This may
181a0 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a   happen if the.*
181b0 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74  * program uses t
181c0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
181d0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20  L function], or 
181e0 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61  if some other ca
181f0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
18200 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74  on invokes sqlit
18210 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72  e3_changes() dir
18220 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c  ectly. Essential
18230 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ly:.** .** <ul>.
18240 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f  **   <li> ^(Befo
18250 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72  re entering a tr
18260 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68  igger program th
18270 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18280 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71   by.**        sq
18290 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
182a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65  function is save
182b0 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69  d. After the tri
182c0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a  gger program .**
182d0 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69          has fini
182e0 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e  shed, the origin
182f0 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74  al value is rest
18300 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20  ored.)^.** .**  
18310 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61   <li> ^(Within a
18320 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
18330 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50   each INSERT, UP
18340 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20  DATE and DELETE 
18350 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65  .**        state
18360 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61  ment sets the va
18370 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
18380 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18390 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f  ) .**        upo
183a0 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20  n completion as 
183b0 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73  normal. Of cours
183c0 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69  e, this value wi
183d0 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a  ll not include .
183e0 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68  **        any ch
183f0 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20  anges performed 
18400 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c  by sub-triggers,
18410 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f   as the sqlite3_
18420 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
18430 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20       value will 
18440 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73  be saved and res
18450 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68  tored after each
18460 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73   sub-trigger has
18470 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e   run.)^.** </ul>
18480 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65  .** .** ^This me
18490 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20  ans that if the 
184a0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
184b0 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c  nction (or simil
184c0 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62  ar) is used.** b
184d0 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45  y the first INSE
184e0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
184f0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
18500 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
18510 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20   it .** returns 
18520 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74  the value as set
18530 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e   when the callin
18540 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61  g statement bega
18550 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  n executing..** 
18560 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62  ^If it is used b
18570 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20  y the second or 
18580 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20  subsequent such 
18590 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
185a0 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70   a trigger .** p
185b0 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75  rogram, the valu
185c0 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65  e returned refle
185d0 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  cts the number o
185e0 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20  f rows modified 
185f0 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69  by the .** previ
18600 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ous INSERT, UPDA
18610 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
18620 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
18630 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
18640 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
18650 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
18660 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
18670 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
18680 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
18690 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
186a0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
186b0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
186c0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
186d0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
186e0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
186f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18700 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
18710 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
18720 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
18730 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18740 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
18750 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
18760 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
18770 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18780 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
18790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
187a0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
187b0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
187c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
187d0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
187e0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
187f0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
18800 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
18810 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
18820 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
18830 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
18840 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
18850 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
18860 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
18870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18880 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
18890 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
188a0 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
188b0 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
188c0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
188d0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
188e0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
188f0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
18900 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
18910 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
18920 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18930 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
18940 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
18950 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
18960 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
18970 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
18980 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
18990 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
189a0 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
189b0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
189c0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
189d0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
189e0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
189f0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
18a00 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
18a10 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
18a20 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
18a30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
18a40 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
18a50 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
18a60 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
18a70 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
18a80 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
18a90 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
18aa0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
18ab0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
18ac0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
18ad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18ae0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
18af0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18b00 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
18b10 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
18b20 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
18b30 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
18b40 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
18b50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
18b60 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
18b70 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18b80 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
18b90 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
18ba0 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
18bb0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
18bc0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
18bd0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
18be0 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
18bf0 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
18c00 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
18c10 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
18c20 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
18c30 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
18c40 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
18c50 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
18c60 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
18c70 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
18c80 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
18c90 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
18ca0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
18cb0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
18cc0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
18cd0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
18ce0 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
18cf0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
18d00 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
18d10 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
18d20 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
18d30 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
18d40 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
18d50 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
18d60 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
18d70 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18d80 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
18d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18da0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
18db0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
18dc0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
18dd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
18de0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
18df0 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
18e00 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
18e10 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
18e20 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
18e30 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18e40 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
18e50 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
18e60 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
18e70 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
18e80 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
18e90 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
18ea0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
18eb0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
18ec0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
18ed0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
18ee0 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
18ef0 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
18f00 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
18f10 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
18f20 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
18f30 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
18f40 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
18f50 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
18f60 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
18f70 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
18f80 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
18f90 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
18fa0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
18fb0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
18fc0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
18fd0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
18fe0 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
18ff0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
19000 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
19010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19020 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
19030 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
19040 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
19050 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
19060 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
19070 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
19080 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
19090 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
190a0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
190b0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
190c0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
190d0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
190e0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
190f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19100 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
19110 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
19120 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
19130 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
19140 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
19150 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
19160 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
19170 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
19180 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
19190 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
191a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
191b0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
191c0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
191d0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
191e0 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
191f0 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
19200 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
19210 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
19220 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
19230 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
19240 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
19250 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
19260 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
19270 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
19280 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
19290 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
192a0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
192b0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
192c0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
192d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
192e0 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
192f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19300 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
19310 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
19320 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
19330 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
19340 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
19350 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
19360 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
19370 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
19380 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
19390 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
193a0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
193b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
193c0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
193d0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
193e0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
193f0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
19400 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
19410 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
19420 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
19430 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
19440 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
19450 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
19460 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
19470 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
19480 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
19490 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
194a0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
194b0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
194c0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
194d0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
194e0 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
194f0 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
19500 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
19510 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
19520 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
19530 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
19540 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
19550 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
19560 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
19570 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
19580 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
19590 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
195a0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
195b0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
195c0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
195d0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
195e0 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
195f0 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
19600 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
19610 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
19620 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
19630 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
19640 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
19650 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
19660 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
19670 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
19680 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
19690 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
196a0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
196b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
196c0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
196d0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
196e0 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
196f0 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
19700 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
19710 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
19720 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
19730 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
19740 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
19750 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
19760 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
19770 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
19780 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
19790 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
197a0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
197b0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
197c0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
197d0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
197e0 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
197f0 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
19800 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
19810 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
19820 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19830 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
19840 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
19850 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
19860 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
19870 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
19880 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
19890 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
198a0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
198b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
198c0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
198d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
198e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
198f0 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
19900 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
19910 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
19920 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
19930 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
19940 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19950 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
19960 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
19970 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
19980 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
19990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
199a0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
199b0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
199c0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
199d0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
199e0 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
199f0 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
19a00 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  dler}.** METHOD:
19a10 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
19a20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
19a30 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20  _handler(D,X,P) 
19a40 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
19a50 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19a60 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74   X.** that might
19a70 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
19a80 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
19a90 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
19aa0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  pt is made to ac
19ab0 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20  cess a database 
19ac0 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64  table associated
19ad0 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61   with.** [databa
19ae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
19af0 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68   when another th
19b00 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
19b10 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65  ss has the table
19b20 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20   locked..** The 
19b30 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
19b40 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  dler() interface
19b50 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   is used to impl
19b60 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65  ement.** [sqlite
19b70 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
19b80 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75  ] and [PRAGMA bu
19b90 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a  sy_timeout]..**.
19ba0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
19bb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
19bc0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
19bd0 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  USY].** is retur
19be0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
19bf0 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
19c00 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
19c10 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
19c20 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
19c30 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
19c40 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
19c50 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
19c60 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
19c70 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
19c80 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
19c90 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
19ca0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
19cb0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
19cc0 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
19cd0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
19ce0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
19cf0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
19d00 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
19d10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
19d20 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
19d30 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
19d40 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
19d50 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
19d60 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73  invoked previous
19d70 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ly for the same 
19d80 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
19d90 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
19da0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19db0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
19dc0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
19dd0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
19de0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
19df0 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
19e00 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
19e10 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
19e20 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
19e30 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
19e40 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
19e50 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
19e60 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
19e70 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
19e80 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
19e90 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
19ea0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
19eb0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
19ec0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
19ed0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
19ee0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
19ef0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
19f00 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
19f10 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
19f20 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
19f30 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
19f40 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
19f50 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
19f60 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
19f70 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
19f80 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
19f90 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
19fa0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
19fb0 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
19fc0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
19fd0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
19fe0 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
19ff0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1a000 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1a010 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1a020 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1a030 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1a040 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1a050 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1a060 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1a070 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1a080 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1a090 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1a0a0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1a0b0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1a0c0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1a0d0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1a0e0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1a0f0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1a100 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1a110 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1a120 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1a130 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1a140 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1a150 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1a160 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1a170 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1a180 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1a190 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1a1a0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1a1b0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1a1c0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1a1d0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1a1e0 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1a1f0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1a200 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1a210 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1a220 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1a230 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1a240 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1a250 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1a260 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1a270 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1a280 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1a290 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1a2a0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
1a2b0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
1a2c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
1a2d0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
1a2e0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
1a2f0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
1a300 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
1a310 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
1a320 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
1a330 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
1a340 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
1a350 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1a360 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
1a370 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
1a380 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
1a390 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
1a3a0 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
1a3b0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1a3c0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1a3d0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1a3e0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1a3f0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1a400 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a410 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1a420 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1a430 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
1a440 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
1a450 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
1a460 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
1a470 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1a480 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1a490 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1a4a0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1a4b0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1a4c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a4d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1a4e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1a4f0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1a500 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1a510 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
1a520 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1a530 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1a540 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
1a550 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a560 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1a570 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1a580 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1a590 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1a5a0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1a5b0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1a5c0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1a5d0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1a5e0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1a5f0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1a600 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1a610 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1a620 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1a630 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1a640 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1a650 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1a660 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1a670 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1a680 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1a690 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1a6a0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1a6b0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1a6c0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1a6d0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1a6e0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1a6f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1a700 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1a710 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1a720 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1a730 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1a740 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1a750 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1a760 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1a770 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1a780 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1a790 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1a7a0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1a7b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a7c0 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1a7d0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1a7e0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1a7f0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1a800 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1a810 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1a820 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1a830 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1a840 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1a850 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1a860 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1a870 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1a880 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1a890 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1a8a0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1a8b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1a8c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a8d0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1a8e0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1a8f0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45  ng Queries.** ME
1a900 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1a910 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1a920 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1a930 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1a940 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1a950 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1a960 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1a970 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1a980 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1a990 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1a9a0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1a9b0 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1a9c0 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1a9d0 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1a9e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a9f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1aa00 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1aa10 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1aa20 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1aa30 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1aa40 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1aa50 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1aa60 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1aa70 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1aa80 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1aa90 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1aaa0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1aab0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1aac0 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1aad0 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1aae0 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1aaf0 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1ab00 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1ab10 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1ab20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1ab30 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1ab40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1ab50 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1ab60 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1ab70 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1ab80 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1ab90 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1aba0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1abb0 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1abc0 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1abd0 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1abe0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1abf0 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1ac00 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1ac10 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1ac20 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1ac30 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1ac40 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1ac50 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1ac60 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1ac70 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1ac80 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1ac90 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1aca0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1acb0 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1acc0 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1acd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1ace0 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1acf0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1ad00 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1ad10 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1ad20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1ad30 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1ad40 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1ad50 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1ad60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1ad70 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1ad80 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1ad90 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1ada0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1adb0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1adc0 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1add0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1ade0 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1adf0 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1ae00 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1ae10 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1ae20 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ae30 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1ae40 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1ae50 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1ae60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1ae70 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1ae80 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1ae90 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1aea0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1aeb0 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1aec0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1aed0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1aee0 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1aef0 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1af00 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1af10 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1af20 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1af30 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1af40 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1af50 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1af60 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1af70 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1af80 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1af90 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1afa0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1afb0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1afc0 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1afd0 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1afe0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1aff0 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1b000 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b010 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1b020 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b030 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1b040 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b050 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1b060 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1b070 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1b080 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1b090 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1b0a0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1b0b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b0c0 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1b0d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b0e0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1b0f0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1b100 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1b110 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1b120 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1b130 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1b140 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1b150 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1b160 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1b170 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1b180 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1b190 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1b1a0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1b1b0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1b1c0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1b1d0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1b1e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1b1f0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1b200 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1b210 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b220 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1b230 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1b240 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1b250 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b260 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1b270 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1b280 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1b290 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1b2a0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1b2b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1b2c0 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1b2d0 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1b2e0 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1b2f0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1b300 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1b310 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1b320 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1b330 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1b340 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b350 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1b360 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1b370 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1b380 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1b390 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b3a0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1b3b0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1b3c0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1b3d0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1b3e0 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1b3f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1b400 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1b410 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1b420 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1b430 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1b440 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1b450 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1b460 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1b470 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1b480 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1b490 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1b4a0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1b4b0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1b4c0 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1b4d0 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1b4e0 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1b4f0 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1b500 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1b510 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1b520 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1b530 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1b540 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1b550 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1b560 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b570 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1b580 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1b590 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1b5a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1b5b0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1b5c0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1b5d0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1b5e0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1b5f0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1b600 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1b610 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1b620 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1b630 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1b640 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1b650 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1b660 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1b670 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1b680 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1b690 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1b6a0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1b6b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1b6c0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1b6d0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1b6e0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1b6f0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1b700 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1b710 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b720 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1b730 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1b740 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1b750 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1b760 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1b770 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1b780 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1b790 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1b7a0 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1b7b0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1b7c0 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1b7d0 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1b7e0 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1b7f0 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1b800 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1b810 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1b820 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1b830 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1b840 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1b850 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1b860 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1b870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1b880 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b890 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1b8a0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1b8b0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1b8c0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1b8d0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1b8e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1b8f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1b900 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1b910 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1b920 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1b930 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1b940 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1b950 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1b960 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b970 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1b980 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1b990 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1b9a0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1b9b0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1b9c0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1b9d0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1b9e0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1b9f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1ba00 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1ba10 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1ba20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1ba30 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1ba40 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1ba50 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1ba60 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1ba70 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1ba80 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1ba90 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1baa0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1bab0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1bac0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1bad0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1bae0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1baf0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1bb00 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1bb10 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1bb20 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1bb30 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1bb40 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1bb50 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1bb60 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1bb70 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1bb80 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1bb90 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1bba0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1bbb0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1bbc0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1bbd0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1bbe0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1bbf0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1bc00 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1bc10 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1bc20 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1bc30 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1bc40 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1bc50 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1bc60 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1bc70 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1bc80 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1bc90 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1bca0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1bcb0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1bcc0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1bcd0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1bce0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1bcf0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1bd00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1bd10 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1bd20 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1bd30 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1bd40 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1bd50 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1bd60 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1bd70 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1bd80 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1bd90 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1bda0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1bdb0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1bdc0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1bdd0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1bde0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1bdf0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1be00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1be10 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1be20 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1be30 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1be40 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1be50 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1be60 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1be70 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1be80 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1be90 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1bea0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1beb0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1bec0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1bed0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1bee0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1bef0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1bf00 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1bf10 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1bf20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1bf30 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1bf40 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1bf50 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1bf60 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1bf70 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1bf80 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1bf90 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1bfa0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1bfb0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1bfc0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1bfd0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1bfe0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1bff0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1c000 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1c010 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1c020 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1c030 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1c040 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1c050 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1c060 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1c070 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1c080 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1c090 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1c0a0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1c0b0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1c0c0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1c0d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c0e0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1c0f0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1c100 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s 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 4f 6e  kquote>.**.** On
1c130 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1c140 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1c150 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1c160 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c170 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c180 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1c190 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1c1a0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1c1b0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1c1c0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1c1d0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1c1e0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1c1f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1c200 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1c210 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c220 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1c230 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1c240 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1c250 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1c260 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1c270 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1c280 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1c290 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c2a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c2b0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1c2c0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1c2d0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1c2e0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1c2f0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1c300 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1c310 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1c320 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1c330 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1c340 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1c350 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1c360 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c370 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1c380 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1c390 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1c3a0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1c3b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c3c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1c3d0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1c3e0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1c3f0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1c400 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1c410 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1c420 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1c430 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1c440 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1c450 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1c460 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1c470 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1c480 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1c490 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1c4a0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1c4b0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1c4c0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1c4d0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1c4e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1c4f0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1c500 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1c510 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1c520 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1c530 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1c540 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1c550 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1c560 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1c570 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1c580 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c590 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1c5a0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c5b0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1c5c0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1c5d0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1c5e0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1c5f0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1c600 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1c610 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1c620 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c630 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1c640 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1c650 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1c660 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1c670 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1c680 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1c690 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1c6a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1c6b0 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1c6c0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1c6d0 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1c6e0 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1c6f0 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1c700 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1c710 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1c720 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1c730 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1c740 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1c750 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1c760 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1c770 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1c780 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1c790 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1c7a0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1c7b0 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1c7c0 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1c7d0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1c7e0 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1c7f0 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1c800 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1c810 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1c820 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1c830 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1c840 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1c850 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1c860 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1c870 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1c880 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1c890 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1c8a0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1c8b0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1c8c0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1c8d0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1c8e0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1c8f0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c900 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1c910 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1c920 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1c930 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1c940 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1c950 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1c960 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1c970 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1c980 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1c990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1c9a0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1c9b0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1c9c0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1c9d0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1c9e0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1c9f0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1ca00 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1ca10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1ca20 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1ca30 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1ca40 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1ca50 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1ca60 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1ca70 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1ca80 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1ca90 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1caa0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1cab0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1cac0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1cad0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1cae0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1caf0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1cb00 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1cb10 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1cb20 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1cb30 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1cb40 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1cb50 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1cb60 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1cb70 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1cb80 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1cb90 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1cba0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1cbb0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1cbc0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1cbd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1cbe0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1cbf0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1cc00 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1cc10 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1cc20 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1cc30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1cc40 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1cc50 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1cc60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1cc70 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1cc80 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1cc90 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1cca0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1ccb0 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1ccc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1ccd0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1cce0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1ccf0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1cd00 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1cd10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1cd20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1cd30 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1cd40 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1cd50 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1cd60 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1cd70 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1cd80 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1cd90 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1cda0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1cdb0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1cdc0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1cdd0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1cde0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1cdf0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1ce00 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1ce10 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1ce20 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1ce30 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1ce40 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1ce50 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1ce60 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1ce70 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1ce80 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1ce90 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1cea0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1ceb0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1cec0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1ced0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1cee0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1cef0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1cf00 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1cf10 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1cf20 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1cf30 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1cf40 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1cf50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1cf60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1cf70 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1cf80 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1cf90 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1cfa0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1cfb0 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1cfc0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1cfd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1cfe0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1cff0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d000 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1d010 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1d020 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1d030 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1d040 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1d050 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1d060 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1d070 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d080 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1d090 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1d0a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1d0b0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1d0c0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1d0d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1d0e0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1d0f0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1d100 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1d110 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1d120 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1d130 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1d140 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1d150 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1d160 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1d170 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1d180 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1d190 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1d1a0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1d1b0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1d1c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1d1d0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1d1e0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1d1f0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1d200 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1d210 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1d220 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1d230 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1d240 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1d250 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1d260 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1d270 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1d280 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1d290 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1d2a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d2b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1d2c0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1d2d0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1d2e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1d2f0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1d300 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1d310 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1d320 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1d330 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1d340 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1d350 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1d360 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1d370 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1d380 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1d390 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1d3a0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1d3b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d3c0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1d3d0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1d3e0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1d3f0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1d400 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1d410 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1d420 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1d430 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1d440 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1d450 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1d460 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1d470 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1d480 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1d490 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1d4a0 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1d4b0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1d4c0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d4d0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1d4e0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1d4f0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1d500 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1d510 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1d520 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1d530 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1d540 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1d550 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1d560 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1d570 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1d580 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d590 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1d5a0 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1d5b0 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1d5c0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1d5d0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1d5e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1d5f0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1d600 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1d610 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1d620 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1d630 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1d640 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1d650 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1d660 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1d670 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1d680 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1d690 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1d6a0 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1d6b0 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1d6c0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1d6d0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1d6e0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1d6f0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1d700 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1d710 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1d720 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1d730 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1d740 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1d750 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1d760 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1d770 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1d780 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1d790 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1d7a0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1d7b0 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1d7c0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1d7d0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1d7e0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1d7f0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1d800 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1d810 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1d820 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1d830 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1d840 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1d850 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1d860 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1d870 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1d880 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1d890 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1d8a0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1d8b0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1d8c0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1d8d0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1d8e0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1d8f0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1d900 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1d910 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1d920 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1d930 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1d940 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1d950 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1d960 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1d970 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1d980 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1d990 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1d9a0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1d9b0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1d9c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1d9d0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1d9e0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1d9f0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1da00 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1da10 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1da20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1da30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1da40 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1da50 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1da60 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1da70 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1da80 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1da90 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1daa0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1dab0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1dac0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1dad0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1dae0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1daf0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1db00 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1db10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1db20 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1db30 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1db40 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1db50 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1db60 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1db70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1db80 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1db90 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1dba0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1dbb0 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
1dbc0 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
1dbd0 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1dbe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1dbf0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1dc00 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1dc10 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1dc20 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1dc30 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1dc40 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1dc50 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1dc60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1dc70 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1dc80 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1dc90 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1dca0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1dcb0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1dcc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1dcd0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1dce0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1dcf0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1dd00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1dd10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1dd20 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1dd30 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1dd40 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1dd50 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1dd60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1dd70 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1dd80 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1dd90 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1dda0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1ddb0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1ddc0 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1ddd0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1dde0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1ddf0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1de00 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1de10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1de20 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1de30 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1de40 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1de50 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1de60 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1de70 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1de80 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1de90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1dea0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1deb0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1dec0 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1ded0 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1dee0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1def0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1df00 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1df10 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1df20 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1df30 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1df40 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1df50 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1df60 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1df70 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1df80 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1df90 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1dfa0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1dfb0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1dfc0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1dfd0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1dfe0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1dff0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1e000 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1e010 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1e020 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1e030 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1e040 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1e050 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1e060 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1e070 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1e080 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1e090 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1e0a0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1e0b0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1e0c0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1e0d0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1e0e0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1e0f0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1e100 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1e110 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1e120 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1e130 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1e140 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1e150 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1e160 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1e170 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1e180 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1e190 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1e1a0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1e1b0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1e1c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1e1d0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1e1e0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1e1f0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1e200 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1e210 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1e220 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1e230 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1e240 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1e250 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1e260 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1e270 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1e280 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1e290 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1e2a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1e2b0 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1e2c0 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1e2d0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1e2e0 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1e2f0 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1e300 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1e310 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1e320 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1e330 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1e340 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1e350 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1e360 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1e370 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1e380 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1e390 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1e3a0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1e3b0 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1e3c0 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1e3d0 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1e3e0 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1e3f0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1e400 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1e410 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1e420 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1e430 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1e440 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1e450 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1e460 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1e470 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1e480 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1e490 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1e4a0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1e4b0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
1e4c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1e4d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1e4e0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1e4f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e500 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1e510 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1e520 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1e530 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1e540 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1e550 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1e560 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1e570 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1e580 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1e590 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1e5a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e5b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1e5c0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1e5d0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1e5e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e5f0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1e600 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e610 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1e620 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1e630 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1e640 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1e650 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1e660 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1e670 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1e680 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1e690 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1e6a0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1e6b0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1e6c0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1e6d0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1e6e0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1e6f0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1e700 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1e710 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1e720 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1e730 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1e740 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1e750 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1e760 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1e770 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1e780 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1e790 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1e7a0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1e7b0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1e7c0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1e7d0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1e7e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e7f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1e800 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1e810 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1e820 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1e830 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1e840 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1e850 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1e860 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1e870 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1e880 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1e890 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1e8a0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1e8b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1e8c0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1e8d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1e8e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1e8f0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1e900 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1e910 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1e920 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1e930 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1e940 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1e950 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e960 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1e970 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1e980 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1e990 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1e9a0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1e9b0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1e9c0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1e9d0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1e9e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1e9f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1ea00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ea10 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1ea20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1ea30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1ea40 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ea50 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1ea60 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1ea70 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1ea80 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1ea90 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1eaa0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1eab0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1eac0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1ead0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1eae0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1eaf0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1eb00 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1eb10 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1eb20 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1eb30 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1eb40 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1eb50 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1eb60 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1eb70 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1eb80 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1eb90 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1eba0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1ebb0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1ebc0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1ebd0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1ebe0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1ebf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1ec00 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1ec10 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1ec20 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1ec30 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1ec40 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1ec50 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1ec60 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1ec70 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1ec80 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1ec90 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1eca0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1ecb0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1ecc0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1ecd0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1ece0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
1ecf0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
1ed00 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
1ed10 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1ed20 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
1ed30 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1ed40 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
1ed50 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1ed60 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
1ed70 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
1ed80 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
1ed90 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
1eda0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
1edb0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
1edc0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
1edd0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
1ede0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
1edf0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
1ee00 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
1ee10 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
1ee20 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
1ee30 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
1ee40 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
1ee50 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1ee60 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
1ee70 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
1ee80 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
1ee90 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
1eea0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
1eeb0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
1eec0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
1eed0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
1eee0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
1eef0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
1ef00 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
1ef10 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
1ef20 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
1ef30 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
1ef40 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
1ef50 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
1ef60 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
1ef70 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
1ef80 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
1ef90 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
1efa0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
1efb0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
1efc0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
1efd0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
1efe0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
1eff0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
1f000 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
1f010 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
1f020 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1f030 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
1f040 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
1f050 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
1f060 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
1f070 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
1f080 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
1f090 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
1f0a0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
1f0b0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
1f0c0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
1f0d0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
1f0e0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
1f0f0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
1f100 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
1f110 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
1f120 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
1f130 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
1f140 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
1f150 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
1f160 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
1f170 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
1f180 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
1f190 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
1f1a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1f1b0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
1f1c0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
1f1d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1f1e0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
1f1f0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
1f200 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
1f210 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
1f220 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
1f230 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
1f240 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
1f250 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1f260 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
1f270 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f280 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1f290 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1f2a0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1f2b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f2c0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1f2d0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
1f2e0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
1f2f0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1f300 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1f310 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1f320 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1f330 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1f340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1f350 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1f360 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1f370 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1f380 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
1f390 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f3a0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
1f3b0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
1f3c0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1f3d0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
1f3e0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
1f3f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
1f400 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
1f410 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
1f420 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
1f430 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
1f440 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
1f450 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
1f460 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
1f470 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
1f480 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1f490 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
1f4a0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
1f4b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1f4c0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
1f4d0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
1f4e0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1f4f0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
1f500 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
1f510 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
1f520 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
1f530 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
1f540 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f550 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
1f560 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
1f570 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
1f580 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1f590 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
1f5a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1f5b0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
1f5c0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
1f5d0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
1f5e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
1f5f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1f600 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1f610 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1f620 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1f630 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1f640 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1f650 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1f660 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1f670 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1f680 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1f690 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1f6a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f6b0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1f6c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1f6d0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
1f6e0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
1f6f0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
1f700 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
1f710 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
1f720 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
1f730 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
1f740 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
1f750 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
1f760 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1f770 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1f780 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
1f790 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
1f7a0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1f7b0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1f7c0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
1f7d0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
1f7e0 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
1f7f0 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
1f800 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
1f810 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1f820 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1f830 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1f840 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1f850 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1f860 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1f870 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1f880 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1f890 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1f8a0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1f8b0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1f8c0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1f8d0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1f8e0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1f8f0 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1f900 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1f910 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f920 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1f930 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1f940 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1f950 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1f960 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1f970 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1f980 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1f990 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1f9a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1f9b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1f9c0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1f9d0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1f9e0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1f9f0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1fa00 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1fa10 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1fa20 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1fa30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fa40 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1fa50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1fa60 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1fa70 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1fa80 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1fa90 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1faa0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1fab0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1fac0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1fad0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1fae0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1faf0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1fb00 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1fb10 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1fb20 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1fb30 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1fb40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1fb50 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1fb60 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1fb70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fb80 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1fb90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1fba0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1fbb0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1fbc0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1fbd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1fbe0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1fbf0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1fc00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1fc10 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1fc20 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1fc30 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1fc40 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1fc50 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1fc60 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1fc70 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1fc80 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1fc90 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1fca0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1fcb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fcc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1fcd0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1fce0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1fcf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1fd00 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1fd10 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1fd20 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1fd30 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fd40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1fd50 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1fd60 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1fd70 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1fd80 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fd90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fda0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1fdb0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1fdc0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1fdd0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fde0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fdf0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1fe00 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1fe10 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1fe20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fe30 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1fe40 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1fe50 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1fe60 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1fe70 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1fe80 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1fe90 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1fea0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1feb0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1fec0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1fed0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1fee0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1fef0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1ff00 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1ff10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ff20 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1ff30 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1ff40 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1ff50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ff60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ff70 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1ff80 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1ff90 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1ffa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ffb0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ffc0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1ffd0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1ffe0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1fff0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20000 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20010 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
20020 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
20030 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20040 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20050 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20060 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
20070 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
20080 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20090 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
200a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
200b0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
200c0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
200d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
200e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
200f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20100 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
20110 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
20120 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
20130 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20150 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
20160 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
20170 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
20180 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
201a0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
201b0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
201c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
201d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
201e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
201f0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
20200 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
20210 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
20220 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
20240 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
20250 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
20260 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20270 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
20290 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
202a0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
202b0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
202c0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
202d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
202e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
202f0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
20300 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
20310 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
20320 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
20330 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
20340 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
20350 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
20360 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20370 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
20380 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
20390 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
203a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
203b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
203c0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
203d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
203e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
203f0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
20400 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
20410 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
20420 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
20430 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
20440 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20450 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20460 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
20470 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
20480 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
20490 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
204a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
204b0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
204c0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
204d0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
204e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
204f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20500 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
20510 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
20520 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
20530 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20540 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20550 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
20560 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
20570 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20580 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
205a0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
205b0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
205c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
205d0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
205e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
205f0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
20600 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
20610 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
20620 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
20630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20640 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
20650 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
20660 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
20670 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
20680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20690 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
206a0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
206b0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
206c0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
206d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
206e0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
206f0 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
20700 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
20710 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
20720 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
20730 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
20740 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
20750 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
20760 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
20770 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
20780 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
20790 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
207a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
207b0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
207c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
207d0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
207e0 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
207f0 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
20800 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
20810 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
20820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
20830 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
20840 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
20850 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
20860 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
20870 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
20880 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
20890 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
208a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
208b0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
208c0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
208d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
208e0 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
208f0 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
20900 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
20910 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
20920 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
20930 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
20940 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
20950 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
20960 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
20970 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
20980 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
20990 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
209a0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
209b0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
209c0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
209d0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
209e0 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
209f0 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
20a00 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
20a10 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
20a20 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
20a30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
20a40 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
20a50 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
20a60 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
20a70 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
20a80 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
20a90 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
20aa0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20ab0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
20ac0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
20ad0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
20ae0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
20af0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
20b00 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
20b10 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
20b20 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
20b30 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
20b40 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
20b50 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
20b60 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
20b70 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
20b80 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
20b90 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
20ba0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
20bb0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
20bc0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
20bd0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
20be0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
20bf0 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
20c00 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
20c10 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
20c20 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
20c30 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
20c40 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
20c50 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
20c60 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
20c70 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
20c80 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
20c90 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
20ca0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
20cb0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
20cc0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
20cd0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
20ce0 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
20cf0 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
20d00 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
20d10 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
20d20 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
20d30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
20d40 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
20d50 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
20d60 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
20d70 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
20d80 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
20d90 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
20da0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
20db0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
20dc0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
20dd0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
20de0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
20df0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
20e00 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
20e10 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
20e20 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
20e30 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
20e40 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
20e50 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
20e60 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
20e70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
20e80 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
20e90 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
20ea0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
20eb0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
20ec0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
20ed0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
20ee0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
20ef0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
20f00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20f10 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
20f20 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
20f30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
20f40 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
20f50 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
20f60 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
20f70 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
20f80 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
20f90 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
20fa0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20fb0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
20fc0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
20fd0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
20fe0 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
20ff0 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
21000 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
21010 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
21020 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
21030 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
21040 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
21050 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
21060 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
21070 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
21080 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
21090 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
210a0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
210b0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
210c0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
210d0 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
210e0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
210f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21100 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
21110 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
21120 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
21130 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
21140 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
21150 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
21160 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
21170 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
21180 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
21190 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
211a0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
211b0 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
211c0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
211d0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
211e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
211f0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
21200 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
21210 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
21220 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
21230 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
21240 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
21250 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
21260 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
21270 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
21280 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
21290 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
212a0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
212b0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
212c0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
212d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
212e0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
212f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
21300 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
21310 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21320 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
21330 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
21340 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
21350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21360 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
21370 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
21380 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
21390 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
213a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
213b0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
213c0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
213d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
213e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
213f0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
21400 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
21410 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
21420 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
21430 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
21440 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
21450 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
21460 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
21470 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
21480 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
21490 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
214a0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
214b0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
214c0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
214d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
214e0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
214f0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
21500 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
21510 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
21520 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
21530 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
21540 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
21550 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
21560 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
21570 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
21580 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
21590 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
215a0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
215b0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
215c0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
215d0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
215e0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
215f0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
21600 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
21610 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
21620 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
21630 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
21640 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
21650 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
21660 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
21670 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
21680 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
21690 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
216a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
216b0 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
216c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
216d0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
216e0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
216f0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
21700 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
21710 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
21720 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
21730 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
21740 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
21750 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
21760 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
21770 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
21780 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
21790 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20  ncoding will be 
217a0 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61  UTF-8 for databa
217b0 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  ses created usin
217c0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  g.** sqlite3_ope
217d0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
217e0 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20  pen_v2().  ^The 
217f0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
21800 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a   for databases.*
21810 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  * created using 
21820 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
21830 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20   will be UTF-16 
21840 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
21850 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
21860 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
21870 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
21880 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
21890 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
218a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
218b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
218c0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
218d0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
218e0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
218f0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
21900 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
21910 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
21920 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
21930 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
21940 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
21950 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
21960 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
21970 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
21980 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
21990 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
219a0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
219b0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
219c0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
219d0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
219e0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
219f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
21a00 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
21a10 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
21a20 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
21a30 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
21a40 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
21a50 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
21a60 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
21a70 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
21a80 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
21a90 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
21aa0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
21ab0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
21ac0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
21ad0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
21ae0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
21af0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
21b00 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
21b10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
21b20 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21b30 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
21b40 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
21b50 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
21b60 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
21b70 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
21b80 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
21b90 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21ba0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
21bb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
21bc0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
21bd0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
21be0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
21bf0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
21c00 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
21c10 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
21c20 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
21c30 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
21c40 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
21c50 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
21c60 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
21c70 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
21c80 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
21c90 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
21ca0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
21cb0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
21cc0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
21cd0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
21ce0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
21cf0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
21d00 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
21d10 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
21d20 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
21d30 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
21d40 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
21d50 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
21d60 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
21d70 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
21d80 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
21d90 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
21da0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
21db0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
21dc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
21dd0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
21de0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
21df0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
21e00 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
21e10 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
21e20 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
21e30 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
21e40 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
21e50 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
21e60 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
21e70 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
21e80 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
21e90 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
21ea0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
21eb0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21ec0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
21ed0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
21ee0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
21ef0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
21f00 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
21f10 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
21f20 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
21f30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
21f40 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
21f50 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
21f60 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
21f70 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
21f80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21f90 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
21fa0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
21fb0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
21fc0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
21fd0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
21fe0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
21ff0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
22000 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
22010 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
22020 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
22030 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
22040 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22050 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
22060 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
22070 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
22080 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
22090 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
220a0 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
220b0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
220c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
220d0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
220e0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
220f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
22100 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
22110 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
22120 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
22130 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
22140 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
22150 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
22160 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
22170 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
22180 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
22190 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
221a0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
221b0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
221c0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
221d0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
221e0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
221f0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
22200 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
22210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
22220 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
22230 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
22240 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
22250 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
22260 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
22270 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
22280 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
22290 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
222a0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
222b0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
222c0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
222d0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
222e0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
222f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
22300 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
22310 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
22320 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
22330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22340 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
22350 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
22360 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
22370 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
22380 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
22390 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
223a0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
223b0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
223c0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
223d0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
223e0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
223f0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
22400 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
22410 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
22420 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
22430 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
22440 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
22450 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
22460 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
22470 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
22480 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
22490 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
224a0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
224b0 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
224c0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
224d0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
224e0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
224f0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
22500 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
22510 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
22520 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22530 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
22540 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
22550 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
22560 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
22570 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
22580 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
22590 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
225a0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
225b0 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
225c0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
225d0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
225e0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
225f0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
22600 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
22610 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
22620 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
22630 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
22640 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
22650 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
22660 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
22670 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
22680 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22690 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
226a0 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
226b0 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
226c0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
226d0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
226e0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
226f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
22700 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
22710 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
22720 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
22730 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
22740 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
22750 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
22760 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
22770 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
22780 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
22790 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
227a0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
227b0 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
227c0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
227d0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
227e0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
227f0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
22800 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
22810 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
22820 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
22830 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
22840 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
22850 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
22860 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
22870 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
22880 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
22890 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
228a0 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
228b0 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
228c0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
228d0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
228e0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
228f0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
22900 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
22910 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
22920 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
22930 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
22940 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
22950 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
22960 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
22970 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
22980 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
22990 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
229a0 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
229b0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
229c0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
229d0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
229e0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
229f0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
22a00 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
22a10 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
22a20 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
22a30 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
22a40 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
22a50 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
22a60 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
22a70 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
22a80 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
22a90 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
22aa0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
22ab0 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
22ac0 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74   ^(On windows, t
22ad0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
22ae0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
22af0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
22b00 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
22b10 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
22b20 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )^.**.** [[core 
22b30 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
22b40 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
22b50 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
22b60 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
22b70 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
22b80 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
22b90 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
22ba0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
22bb0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
22bc0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
22bd0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
22be0 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c  ite and its buil
22bf0 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74  t-in [VFSes] int
22c00 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f  erpret the.** fo
22c10 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61  llowing query pa
22c20 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
22c30 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
22c40 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
22c50 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
22c60 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
22c70 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
22c80 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
22c90 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
22ca0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
22cb0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
22cc0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
22cd0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
22ce0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
22cf0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
22d00 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
22d10 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
22d20 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
22d30 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
22d40 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
22d50 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
22d60 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
22d70 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
22d80 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
22d90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
22da0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
22db0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
22dc0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
22dd0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
22de0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
22df0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
22e00 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
22e10 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
22e20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
22e30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22e40 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
22e50 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
22e60 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
22e70 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
22e80 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
22e90 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
22ea0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
22eb0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
22ec0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
22ed0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
22ee0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
22ef0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
22f00 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
22f10 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
22f20 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
22f30 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
22f40 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
22f50 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
22f60 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
22f70 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
22f80 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
22f90 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
22fa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22fb0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
22fc0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
22fd0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
22fe0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
22ff0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
23000 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
23010 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
23020 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
23030 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
23040 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
23050 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
23060 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
23070 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
23080 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
23090 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
230a0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
230b0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
230c0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
230d0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
230e0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
230f0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
23100 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
23110 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
23120 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
23130 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
23140 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
23150 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
23160 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
23170 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
23180 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
23190 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
231a0 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
231b0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
231c0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
231d0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
231e0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
231f0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
23200 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
23210 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
23220 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
23230 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
23240 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
23250 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
23260 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
23270 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
23280 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
23290 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
232a0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
232b0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
232c0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
232d0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
232e0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
232f0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
23300 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
23310 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
23320 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
23330 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
23340 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
23350 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
23360 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
23370 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
23380 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
23390 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
233a0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
233b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
233c0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
233d0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
233e0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
233f0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
23400 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
23410 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
23420 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
23430 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
23440 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
23450 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
23460 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
23470 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
23480 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68  ter indicates wh
23490 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
234a0 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61  .**     [powersa
234b0 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72  fe overwrite] pr
234c0 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64  operty does or d
234d0 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f  oes not apply to
234e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72   the.**     stor
234f0 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69  age media on whi
23500 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
23510 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a  file resides..**
23520 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
23530 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
23540 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
23550 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
23560 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
23570 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
23580 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
23590 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
235a0 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
235b0 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
235c0 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
235d0 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
235e0 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
235f0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
23600 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
23610 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
23620 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
23630 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
23640 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
23650 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
23660 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
23670 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
23680 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
23690 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
236a0 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
236b0 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
236c0 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
236d0 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
236e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
236f0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
23700 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
23710 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
23720 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
23730 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
23740 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
23750 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
23760 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
23770 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
23780 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
23790 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
237a0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
237b0 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
237c0 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
237d0 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
237e0 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
237f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
23800 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
23810 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
23820 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
23830 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
23840 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
23850 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
23860 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
23870 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
23880 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
23890 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
238a0 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
238b0 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
238c0 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
238d0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
238e0 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
238f0 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
23900 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
23910 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
23920 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
23930 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
23940 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
23950 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
23960 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
23970 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
23980 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
23990 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
239a0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
239b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
239c0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
239d0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
239e0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
239f0 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
23a00 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
23a10 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
23a20 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
23a30 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
23a40 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
23a50 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
23a60 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
23a70 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
23a80 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
23a90 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
23aa0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
23ab0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
23ac0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
23ad0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
23ae0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
23af0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
23b00 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
23b10 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
23b20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23b30 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
23b40 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
23b50 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
23b60 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
23b70 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
23b80 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
23b90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23ba0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
23bb0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
23bc0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23bd0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
23be0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
23bf0 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
23c00 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
23c10 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
23c20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
23c30 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
23c40 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
23c50 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
23c60 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
23c70 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
23c80 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
23c90 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
23ca0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
23cb0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
23cc0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
23cd0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
23ce0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
23cf0 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
23d00 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
23d10 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
23d20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
23d30 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
23d40 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
23d50 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
23d60 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
23d70 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
23d80 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
23d90 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
23da0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
23db0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
23dc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
23dd0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
23de0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
23df0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
23e00 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
23e10 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
23e20 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
23e30 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
23e40 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
23e50 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
23e60 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
23e70 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
23e80 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
23e90 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
23ea0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
23eb0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
23ec0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
23ed0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
23ee0 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
23ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
23f00 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
23f10 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
23f20 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
23f30 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
23f40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
23f50 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
23f60 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
23f70 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
23f80 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
23f90 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
23fa0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
23fb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
23fc0 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
23fd0 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
23fe0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
23ff0 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
24000 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
24010 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
24020 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
24030 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
24040 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
24050 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
24060 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
24070 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
24080 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
24090 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
240a0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
240b0 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
240c0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
240d0 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
240e0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
240f0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
24100 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
24110 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
24120 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
24130 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
24140 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
24150 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
24160 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
24170 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
24180 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
24190 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
241a0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
241b0 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
241c0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
241d0 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
241e0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
241f0 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
24200 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
24210 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
24220 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
24230 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
24240 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
24250 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
24260 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
24270 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
24280 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
24290 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
242a0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
242b0 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
242c0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
242d0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
242e0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
242f0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
24300 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
24310 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
24320 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
24330 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
24340 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
24350 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
24360 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
24370 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
24380 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
24390 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
243a0 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
243b0 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
243c0 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
243d0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
243e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
243f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24400 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
24410 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
24420 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
24430 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
24440 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
24450 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
24460 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
24470 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
24480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
24490 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
244a0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
244b0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
244c0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
244d0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
244e0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
244f0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
24500 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
24510 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
24520 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
24530 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
24540 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
24550 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
24560 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
24570 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
24580 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
24590 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
245a0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
245b0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
245c0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
245d0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
245e0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
245f0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
24600 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
24610 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
24620 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
24630 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
24640 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
24650 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
24660 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
24670 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
24680 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
24690 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
246a0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
246b0 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
246c0 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
246d0 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
246e0 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
246f0 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
24700 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24710 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
24720 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
24730 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
24740 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
24750 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
24760 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
24770 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
24780 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
24790 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
247a0 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
247b0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
247c0 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
247d0 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
247e0 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
247f0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
24800 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
24810 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
24820 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
24830 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
24840 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
24850 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
24860 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
24870 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
24880 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
24890 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
248a0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
248b0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
248c0 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
248d0 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
248e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
248f0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
24900 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
24910 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
24920 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
24930 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
24940 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
24950 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
24960 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
24970 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
24980 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
24990 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
249a0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
249b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
249c0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
249d0 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
249e0 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
249f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
24a00 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
24a10 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
24a20 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
24a30 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
24a40 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
24a50 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
24a60 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
24a70 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
24a80 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
24a90 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
24aa0 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
24ab0 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
24ac0 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
24ad0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
24ae0 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
24af0 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
24b00 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
24b10 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
24b20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
24b30 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
24b40 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
24b50 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
24b60 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
24b70 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
24b80 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
24b90 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
24ba0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
24bb0 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
24bc0 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
24bd0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
24be0 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
24bf0 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
24c00 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
24c10 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
24c20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
24c30 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
24c40 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
24c50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24c60 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
24c70 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
24c80 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
24c90 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
24ca0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
24cb0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
24cc0 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
24cd0 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
24ce0 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
24cf0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
24d00 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
24d10 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
24d20 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
24d30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
24d40 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
24d50 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
24d60 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
24d70 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
24d80 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
24d90 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
24da0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
24db0 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
24dc0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
24dd0 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
24de0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
24df0 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
24e00 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
24e10 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
24e20 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
24e30 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
24e40 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
24e50 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
24e60 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
24e70 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
24e80 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24e90 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
24ea0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
24eb0 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
24ec0 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
24ed0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
24ee0 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
24ef0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
24f00 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
24f10 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
24f20 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
24f30 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
24f40 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
24f50 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
24f60 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
24f70 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
24f80 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
24f90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
24fa0 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
24fb0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
24fc0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
24fd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
24fe0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
24ff0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
25000 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
25010 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
25020 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
25030 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
25040 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
25050 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
25060 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
25070 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
25080 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
25090 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
250a0 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
250b0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
250c0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
250d0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
250e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
250f0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
25100 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
25110 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
25120 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
25130 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
25140 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
25150 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
25160 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
25170 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
25180 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
25190 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
251a0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
251b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
251c0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
251d0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
251e0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
251f0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
25200 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
25210 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
25220 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
25230 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
25240 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
25250 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
25260 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
25270 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
25280 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
25290 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
252a0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
252b0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
252c0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
252d0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
252e0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
252f0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
25300 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
25310 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
25320 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
25330 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
25340 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
25350 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25360 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
25370 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
25380 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
25390 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
253a0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
253b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
253c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
253d0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
253e0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
253f0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
25400 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
25410 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
25420 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
25430 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
25440 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
25450 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
25460 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
25470 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
25480 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
25490 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
254a0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
254b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
254c0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
254d0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
254e0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
254f0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
25500 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
25510 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
25520 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
25530 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
25540 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
25550 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
25560 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
25570 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
25580 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
25590 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
255a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
255b0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
255c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
255d0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
255e0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
255f0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
25600 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
25610 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
25620 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
25630 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
25640 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
25650 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
25660 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
25670 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
25680 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
25690 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
256a0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
256b0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
256c0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
256d0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
256e0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
256f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
25700 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
25710 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
25720 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
25730 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
25740 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
25750 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
25760 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
25770 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
25780 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
25790 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
257a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
257b0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
257c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
257d0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
257e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
257f0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
25800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25810 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74  F: Prepared Stat
25820 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
25830 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
25840 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
25850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25860 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
25870 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
25880 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
25890 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
258a0 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20  atement that.** 
258b0 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65  has been compile
258c0 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f  d into binary fo
258d0 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20  rm and is ready 
258e0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e  to be evaluated.
258f0 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20  .**.** Think of 
25900 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
25910 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65  nt as a separate
25920 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61   computer progra
25930 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69  m.  The.** origi
25940 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20  nal SQL text is 
25950 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20  source code.  A 
25960 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25970 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73  nt object .** is
25980 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62   the compiled ob
25990 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20  ject code.  All 
259a0 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  SQL must be conv
259b0 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20  erted into a.** 
259c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
259d0 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e  nt before it can
259e0 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   be run..**.** T
259f0 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66  he life-cycle of
25a00 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
25a10 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75  ement object usu
25a20 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74  ally goes like t
25a30 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
25a40 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
25a50 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
25a60 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69  ement object usi
25a70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
25a80 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c  are_v2()]..** <l
25a90 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
25aa0 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75  o [parameters] u
25ab0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
25ac0 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
25ad0 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
25ae0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
25af0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
25b00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
25b10 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
25b20 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
25b30 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
25b40 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
25b50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
25b60 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
25b70 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
25b80 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
25b90 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
25ba0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
25bb0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
25bc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
25bd0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79  ..** </ol>.*/.ty
25be0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
25bf0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
25c00 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
25c10 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
25c20 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48  e Limits.** METH
25c30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
25c40 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
25c50 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
25c60 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
25c70 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
25c80 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
25c90 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
25ca0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
25cb0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
25cc0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
25cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25ce0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
25cf0 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
25d00 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
25d10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
25d20 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
25d30 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
25d40 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
25d50 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
25d60 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
25d70 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
25d80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
25d90 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
25da0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
25db0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
25dc0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
25dd0 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
25de0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
25df0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
25e00 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
25e10 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
25e20 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
25e30 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
25e40 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
25e50 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
25e60 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
25e70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
25e80 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
25e90 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
25ea0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
25eb0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
25ec0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
25ed0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
25ee0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
25ef0 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
25f00 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
25f10 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
25f20 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
25f30 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
25f40 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
25f50 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
25f60 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
25f70 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
25f80 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
25f90 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
25fa0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
25fb0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
25fc0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
25fd0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
25fe0 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
25ff0 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
26000 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
26010 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
26020 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
26030 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
26040 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
26050 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
26060 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
26070 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
26080 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
26090 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
260a0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
260b0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
260c0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
260d0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
260e0 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
260f0 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
26100 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
26110 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
26120 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
26130 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
26140 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
26150 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
26160 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
26170 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
26180 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
26190 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
261a0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
261b0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
261c0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
261d0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
261e0 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
261f0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
26200 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
26210 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
26220 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
26230 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
26240 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
26250 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
26260 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
26270 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
26280 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
26290 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
262a0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
262b0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
262c0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
262d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
262e0 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
262f0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
26300 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
26310 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
26320 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
26330 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
26340 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
26350 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
26360 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
26370 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
26380 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
26390 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
263a0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
263b0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
263c0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
263d0 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
263e0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
263f0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
26400 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
26410 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
26420 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
26430 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
26440 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
26450 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
26460 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
26470 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
26480 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
26490 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
264a0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
264b0 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
264c0 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
264d0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
264e0 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
264f0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
26500 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
26510 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
26520 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
26530 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
26540 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
26550 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
26560 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
26570 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
26580 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
26590 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
265a0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
265b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
265c0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
265d0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
265e0 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
265f0 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
26600 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
26610 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
26620 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
26630 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
26640 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26650 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
26660 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
26670 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
26680 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26690 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
266a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
266b0 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
266c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
266d0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
266e0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
266f0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
26700 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
26710 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
26720 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26730 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
26740 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
26750 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
26760 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
26770 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26780 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
26790 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
267a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
267b0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
267c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
267d0 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
267e0 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
267f0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
26800 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26810 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
26820 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
26830 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
26840 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
26850 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26860 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
26870 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
26880 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
26890 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
268a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
268b0 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
268c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
268d0 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
268e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
268f0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
26900 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
26910 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
26920 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
26930 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
26940 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c  atement.  This l
26950 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72  imit is not curr
26960 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65  ently.** enforce
26970 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d  d, though that m
26980 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e  ight be added in
26990 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
269a0 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
269b0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
269c0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
269d0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
269e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
269f0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
26a00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26a10 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26a20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
26a30 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
26a40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26a50 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
26a60 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26a70 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
26a80 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26a90 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
26aa0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
26ab0 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
26ac0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
26ad0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
26ae0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
26af0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
26b00 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
26b10 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
26b20 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26b30 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
26b40 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
26b50 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
26b60 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
26b70 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
26b80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26b90 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
26ba0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
26bb0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
26bc0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
26bd0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26be0 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
26bf0 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
26c00 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
26c10 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
26c20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
26c30 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
26c40 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26c50 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
26c60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26c70 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
26c80 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
26c90 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
26ca0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26cb0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
26cc0 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
26cd0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
26ce0 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
26cf0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
26d00 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
26d10 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
26d20 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
26d30 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
26d40 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
26d50 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
26d60 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
26d70 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
26d80 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
26d90 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
26da0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
26db0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
26dc0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
26dd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
26de0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
26df0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
26e00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
26e10 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
26e20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
26e30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
26e40 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
26e50 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
26e60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26e70 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
26e80 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
26e90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26ea0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
26eb0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
26ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26ed0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
26ee0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
26ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26f00 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
26f10 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
26f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26f30 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
26f40 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
26f50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26f60 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
26f70 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
26f80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26f90 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
26fa0 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
26fb0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
26fc0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
26fd0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
26fe0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
26ff0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
27000 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
27010 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52  qlite3.** CONSTR
27020 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
27030 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  tmt.**.** To exe
27040 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
27050 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
27060 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
27070 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
27080 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
27090 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
270a0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
270b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
270c0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
270d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
270e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
270f0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
27100 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
27110 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
27120 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27130 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
27140 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
27150 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
27160 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
27170 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
27180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
27190 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
271a0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
271b0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
271c0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
271d0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
271e0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
271f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
27200 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
27210 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
27220 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
27230 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
27240 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
27250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27260 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
27270 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
27280 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
27290 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  nt is negative, 
272a0 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
272b0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
272c0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
272d0 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
272e0 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
272f0 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e  n it is the.** n
27300 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72  umber of bytes r
27310 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
27320 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72  ^If nByte is zer
27330 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61  o, then no prepa
27340 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
27350 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a   is generated..*
27360 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  * If the caller 
27370 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73  knows that the s
27380 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
27390 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
273a0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  , then.** there 
273b0 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f  is a small perfo
273c0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
273d0 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   to passing an n
273e0 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
273f0 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  hat.** is the nu
27400 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
27410 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
27420 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
27430 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
27440 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
27450 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
27460 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
27470 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
27480 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
27490 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
274a0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
274b0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
274c0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
274d0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
274e0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
274f0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
27500 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
27510 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
27520 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
27530 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
27540 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
27550 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
27560 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
27570 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27580 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
27590 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
275a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
275b0 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
275c0 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
275d0 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
275e0 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
275f0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
27600 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
27610 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
27620 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
27630 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
27640 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
27650 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
27660 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
27670 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
27680 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
27690 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
276a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
276b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
276c0 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
276d0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
276e0 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
276f0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
27700 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
27710 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
27720 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
27730 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
27740 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
27750 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
27760 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
27770 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
27780 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27790 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
277a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
277b0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
277c0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
277d0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
277e0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
277f0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
27800 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
27810 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
27820 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
27830 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
27840 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
27850 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
27860 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
27870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27880 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
27890 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
278a0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
278b0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
278c0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
278d0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
278e0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
278f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27900 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
27910 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
27920 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
27930 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
27940 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
27950 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
27960 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
27970 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
27980 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
27990 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
279a0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
279b0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
279c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
279d0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
279e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
279f0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
27a00 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
27a10 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
27a20 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
27a30 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
27a40 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
27a50 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
27a60 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
27a70 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
27a80 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
27a90 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
27aa0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
27ab0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
27ac0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
27ad0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
27ae0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
27af0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
27b00 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
27b10 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
27b20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
27b30 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
27b40 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
27b50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
27b60 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
27b70 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
27b80 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
27b90 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
27ba0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27bb0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
27bc0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
27bd0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
27be0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
27bf0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
27c00 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
27c10 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
27c20 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
27c30 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
27c40 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
27c50 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
27c60 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
27c70 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
27c80 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
27c90 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
27ca0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
27cb0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
27cc0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
27cd0 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
27ce0 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
27cf0 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
27d00 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
27d10 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
27d20 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
27d30 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
27d40 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
27d50 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
27d60 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
27d70 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
27d80 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
27d90 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
27da0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27db0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
27dc0 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
27dd0 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
27de0 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
27df0 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
27e00 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
27e10 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
27e20 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
27e30 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
27e40 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
27e50 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
27e60 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
27e70 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
27e80 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
27e90 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
27ea0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
27eb0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
27ec0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
27ed0 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
27ee0 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
27ef0 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
27f00 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
27f10 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
27f20 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
27f30 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
27f40 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
27f50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
27f60 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
27f70 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
27f80 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
27f90 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
27fa0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
27fb0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27fc0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
27fd0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
27fe0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
27ff0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
28000 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
28010 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
28020 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
28030 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
28040 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
28050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28060 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
28070 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
28080 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
28090 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
280a0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
280b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
280c0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
280d0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
280e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
280f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
28100 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
28110 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
28120 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
28130 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
28140 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
28150 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
28160 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
28170 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
28180 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
28190 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
281a0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
281b0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
281c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
281d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
281e0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
281f0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
28200 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
28210 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
28220 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
28230 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
28240 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
28250 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
28260 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
28270 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
28280 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
28290 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
282a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
282b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
282c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
282d0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
282e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
282f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
28300 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
28310 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
28320 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
28330 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
28340 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
28350 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
28360 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
28370 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
28380 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
28390 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
283a0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
283b0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
283c0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
283d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
283e0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
283f0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
28400 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
28410 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
28420 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28430 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
28440 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54  ement SQL.** MET
28450 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
28460 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
28470 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
28480 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
28490 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
284a0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
284b0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
284c0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
284d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
284e0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
284f0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
28500 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
28510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28520 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
28530 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
28540 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
28550 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
28560 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
28570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28580 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
28590 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
285a0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
285b0 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
285c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
285d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
285e0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
285f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
28600 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
28610 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
28620 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
28630 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
28640 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
28650 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
28660 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
28670 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
28680 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
28690 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
286a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
286b0 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
286c0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
286d0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
286e0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
286f0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
28700 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
28710 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
28720 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
28730 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
28740 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
28750 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
28760 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
28770 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
28780 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
28790 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
287a0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
287b0 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
287c0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
287d0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
287e0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
287f0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
28800 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
28810 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
28820 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
28830 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
28840 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
28850 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
28860 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
28870 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
28880 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
28890 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
288a0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
288b0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
288c0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
288d0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
288e0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
288f0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
28900 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
28910 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
28920 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
28930 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
28940 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
28950 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
28960 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
28970 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
28980 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
28990 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
289a0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
289b0 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
289c0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
289d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
289e0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
289f0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
28a00 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
28a10 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
28a20 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
28a30 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
28a40 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
28a50 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
28a60 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
28a70 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
28a80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
28a90 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
28aa0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
28ab0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
28ac0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
28ad0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
28ae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
28af0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
28b00 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
28b10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
28b20 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
28b30 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
28b40 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
28b50 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
28b60 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
28b70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
28b80 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
28b90 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
28ba0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
28bb0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
28bc0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
28bd0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
28be0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
28bf0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
28c00 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
28c10 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
28c20 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
28c30 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
28c40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
28c50 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
28c60 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
28c70 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
28c80 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
28c90 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
28ca0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
28cb0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
28cc0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
28cd0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
28ce0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
28cf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
28d00 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
28d10 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
28d20 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
28d30 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
28d40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
28d50 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
28d60 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
28d70 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
28d80 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
28d90 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
28da0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
28db0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
28dc0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
28dd0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
28de0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
28df0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
28e00 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
28e10 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
28e20 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
28e30 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
28e40 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
28e50 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
28e60 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
28e70 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69  ction open..*/.i
28e80 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
28e90 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
28ea0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
28eb0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
28ec0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
28ed0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
28ee0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
28ef0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
28f00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28f10 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
28f20 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
28f30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28f40 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
28f50 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
28f60 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
28f70 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
28f80 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
28f90 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
28fa0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
28fb0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
28fc0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
28fd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28fe0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
28ff0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
29000 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
29010 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
29020 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
29030 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
29040 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
29050 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
29060 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
29070 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
29080 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
29090 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
290a0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
290b0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
290c0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
290d0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
290e0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
290f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
29100 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
29110 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
29120 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
29130 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
29140 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
29150 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
29160 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
29170 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
29180 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
29190 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
291a0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
291b0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
291c0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
291d0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
291e0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
291f0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
29200 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
29210 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
29220 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
29230 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
29240 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
29250 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
29260 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
29270 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
29280 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
29290 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
292a0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
292b0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
292c0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
292d0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
292e0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
292f0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
29300 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
29310 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
29320 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
29330 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
29340 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
29350 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
29360 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
29370 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
29380 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29390 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
293a0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
293b0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
293c0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
293d0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
293e0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
293f0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
29400 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
29410 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
29420 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
29430 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
29440 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
29450 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
29460 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
29470 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
29480 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
29490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
294a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
294b0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
294c0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
294d0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
294e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
294f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29500 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
29510 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
29520 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29530 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
29540 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
29550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
29560 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
29570 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
29580 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29590 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
295a0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
295b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
295c0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
295d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
295e0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
295f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
29600 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
29610 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
29620 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
29630 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
29640 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29650 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
29660 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
29670 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
29680 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29690 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
296a0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
296b0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
296c0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
296d0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
296e0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
296f0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
29700 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
29710 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
29720 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
29730 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
29740 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
29750 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
29760 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
29770 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
29780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
29790 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
297a0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
297b0 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
297c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
297d0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
297e0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
297f0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
29800 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
29810 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29820 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
29830 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
29840 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
29850 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
29860 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
29870 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
29880 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
29890 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
298a0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
298b0 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
298c0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
298d0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
298e0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
298f0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
29900 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
29910 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
29920 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
29930 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
29940 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
29950 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
29960 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
29970 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
29980 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
29990 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ng}.** METHOD: s
299a0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
299b0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
299c0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
299d0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
299e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
299f0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
29a00 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
29a10 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
29a20 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
29a30 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
29a40 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
29a50 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
29a60 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
29a70 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
29a80 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
29a90 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
29aa0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
29ab0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
29ac0 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
29ad0 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
29ae0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
29af0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
29b00 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
29b10 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
29b20 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
29b30 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
29b40 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
29b50 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
29b60 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
29b70 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
29b80 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
29b90 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
29ba0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
29bb0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
29bc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
29bd0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
29be0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29bf0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
29c00 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
29c10 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
29c20 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
29c30 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
29c40 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
29c50 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
29c60 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
29c70 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
29c80 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
29c90 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
29ca0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
29cb0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
29cc0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
29cd0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
29ce0 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
29cf0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
29d00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
29d10 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
29d20 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
29d30 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
29d40 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
29d50 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
29d60 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
29d70 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
29d80 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
29d90 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
29da0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
29db0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
29dc0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
29dd0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
29de0 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
29df0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
29e00 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
29e10 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
29e20 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
29e30 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
29e40 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
29e50 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
29e60 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
29e70 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
29e80 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
29e90 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
29ea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
29eb0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
29ec0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
29ed0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
29ee0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
29ef0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
29f00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29f10 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
29f20 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
29f30 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
29f40 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
29f50 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
29f60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29f70 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
29f80 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
29f90 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
29fa0 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
29fb0 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
29fc0 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
29fd0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
29fe0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
29ff0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2a000 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2a010 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2a020 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2a030 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2a040 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2a050 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2a060 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2a070 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2a080 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2a090 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2a0a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2a0b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2a0c0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2a0d0 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2a0e0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2a0f0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2a100 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2a110 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2a120 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2a130 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2a140 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2a150 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2a160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a170 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2a180 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2a190 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2a1a0 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2a1b0 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2a1c0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2a1d0 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2a1e0 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2a1f0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2a200 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2a210 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2a220 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2a230 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2a240 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2a250 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2a260 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2a270 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2a280 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2a290 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2a2a0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2a2b0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2a2c0 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2a2d0 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2a2e0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2a2f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2a300 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2a310 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2a320 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2a330 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2a340 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2a350 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2a360 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2a370 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2a380 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2a390 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2a3a0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2a3b0 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2a3c0 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2a3d0 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2a3e0 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2a3f0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2a400 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2a410 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2a420 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2a430 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2a440 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2a450 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2a460 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2a470 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2a480 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2a490 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2a4a0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2a4b0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2a4c0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2a4d0 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2a4e0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2a4f0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2a500 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2a510 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2a520 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2a530 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2a540 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2a550 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2a560 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2a570 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2a580 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2a590 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2a5a0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2a5b0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2a5c0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2a5d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2a5e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2a5f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2a600 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2a610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a620 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2a630 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2a640 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2a650 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2a660 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2a670 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2a680 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2a690 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2a6a0 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2a6b0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2a6c0 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2a6d0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2a6e0 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2a6f0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2a700 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2a710 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2a720 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2a730 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2a740 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2a750 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2a760 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2a770 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2a780 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2a790 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2a7a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a7b0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2a7c0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2a7d0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2a7e0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2a7f0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2a800 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2a810 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2a820 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2a830 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2a840 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2a850 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2a860 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2a870 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2a880 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2a890 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2a8a0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2a8b0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2a8c0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2a8d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2a8e0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2a8f0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2a900 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2a910 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2a920 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2a930 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2a940 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2a950 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2a960 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2a970 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2a980 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2a990 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2a9a0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2a9b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2a9c0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2a9d0 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2a9e0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2a9f0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2aa00 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2aa10 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2aa20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2aa30 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2aa40 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2aa50 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2aa60 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2aa70 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2aa80 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2aa90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aaa0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2aab0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2aac0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2aad0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2aae0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2aaf0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2ab00 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2ab10 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2ab20 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2ab30 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2ab40 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2ab50 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2ab60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ab70 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2ab80 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2ab90 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2aba0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2abb0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2abc0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2abd0 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2abe0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2abf0 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2ac00 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2ac10 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2ac20 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2ac30 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2ac40 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2ac50 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2ac60 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2ac70 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2ac80 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2ac90 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2aca0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2acb0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2acc0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2acd0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2ace0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2acf0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2ad00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ad10 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2ad20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2ad30 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2ad40 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2ad50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2ad60 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2ad70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2ad80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ad90 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2ada0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
2adb0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2adc0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
2add0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2ade0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2adf0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
2ae00 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
2ae10 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2ae20 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
2ae30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2ae40 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2ae50 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2ae60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2ae70 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2ae80 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2ae90 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2aea0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2aeb0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2aec0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
2aed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2aee0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aef0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
2af00 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
2af10 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
2af20 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
2af30 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2af40 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2af50 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2af60 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2af70 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2af80 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2af90 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2afa0 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
2afb0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2afc0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
2afd0 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2afe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aff0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
2b000 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
2b010 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
2b020 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2b030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b040 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
2b050 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2b060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2b070 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2b080 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
2b090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b0a0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
2b0b0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45  Parameters.** ME
2b0c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2b0d0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  mt.**.** ^This r
2b0e0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2b0f0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2b100 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2b110 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2b120 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b130 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2b140 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2b150 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2b160 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2b170 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2b180 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2b190 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2b1a0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2b1b0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2b1c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2b1d0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2b1e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2b1f0 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2b200 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2b210 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2b220 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2b230 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2b240 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2b250 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2b260 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2b270 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2b280 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2b290 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2b2a0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2b2b0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2b2c0 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2b2d0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2b2e0 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2b2f0 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2b300 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b310 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2b320 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2b330 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b340 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2b350 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2b360 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b370 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2b380 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b390 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2b3a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b3b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b3c0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2b3d0 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
2b3e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2b3f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2b400 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b410 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2b420 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2b430 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2b440 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2b450 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2b460 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b470 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2b480 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2b490 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2b4a0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2b4b0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2b4c0 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2b4d0 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2b4e0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2b4f0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2b500 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2b510 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2b520 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2b530 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2b540 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2b550 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2b560 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2b570 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2b580 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2b590 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2b5a0 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2b5b0 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2b5c0 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2b5d0 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2b5e0 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2b5f0 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2b600 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2b610 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2b620 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2b630 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2b640 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2b650 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2b660 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2b670 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2b680 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2b690 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2b6a0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2b6b0 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2b6c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2b6d0 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2b6e0 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2b6f0 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2b700 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2b710 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2b720 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2b730 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b740 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2b750 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2b760 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2b770 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2b780 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b790 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2b7a0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2b7b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b7c0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2b7d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b7e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b7f0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2b800 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2b810 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2b820 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2b830 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2b840 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Name.** METHOD: 
2b850 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b860 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2b870 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2b880 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2b890 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2b8a0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2b8b0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2b8c0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2b8d0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2b8e0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2b8f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2b900 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2b910 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2b920 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2b930 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2b940 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2b950 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2b960 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2b970 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2b980 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2b990 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2b9a0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2b9b0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2b9c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b9d0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2b9e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2b9f0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2ba00 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2ba10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2ba20 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2ba30 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2ba40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2ba50 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2ba60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ba70 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2ba80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2ba90 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2baa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2bab0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2bac0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2bad0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  d Statement.** M
2bae0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2baf0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  tmt.**.** ^Contr
2bb00 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
2bb10 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
2bb20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2bb30 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
2bb40 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2bb50 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
2bb60 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
2bb70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2bb80 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
2bb90 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
2bba0 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
2bbb0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
2bbc0 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
2bbd0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2bbe0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2bbf0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2bc00 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
2bc10 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
2bc20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2bc30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
2bc40 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2bc50 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2bc60 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2bc70 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2bc80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bc90 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2bca0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2bcb0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2bcc0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2bcd0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2bce0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2bcf0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2bd00 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2bd10 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2bd20 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2bd30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2bd40 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2bd50 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2bd60 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2bd70 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2bd80 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
2bd90 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2bda0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2bdb0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2bdc0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2bdd0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
2bde0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
2bdf0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2be00 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2be10 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
2be20 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
2be30 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2be40 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2be50 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2be60 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
2be70 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
2be80 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
2be90 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2bea0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2beb0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
2bec0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
2bed0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2bee0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2bef0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
2bf00 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2bf10 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2bf20 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
2bf30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2bf40 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
2bf50 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
2bf60 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
2bf70 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
2bf80 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2bf90 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
2bfa0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
2bfb0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2bfc0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
2bfd0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2bfe0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2bff0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2c000 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2c010 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2c020 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2c030 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2c040 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2c050 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2c060 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2c070 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
2c080 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2c090 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
2c0a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2c0b0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
2c0c0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
2c0d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
2c0e0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
2c0f0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
2c100 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
2c110 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
2c120 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
2c130 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
2c140 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
2c150 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2c160 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2c170 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2c180 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
2c190 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2c1a0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
2c1b0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
2c1c0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
2c1d0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
2c1e0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
2c1f0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
2c200 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2c210 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
2c220 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
2c230 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
2c240 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
2c250 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
2c260 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2c270 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c280 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2c290 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
2c2a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2c2b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
2c2c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2c2d0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
2c2e0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
2c2f0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
2c300 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
2c310 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c320 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2c330 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2c340 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2c350 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2c360 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2c370 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2c380 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2c390 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2c3a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2c3b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2c3c0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2c3d0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2c3e0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2c3f0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2c400 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2c410 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2c420 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2c430 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2c440 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2c450 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2c460 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2c470 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2c480 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2c490 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2c4a0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2c4b0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2c4c0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2c4d0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2c4e0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2c4f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c500 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2c510 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2c520 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2c530 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2c540 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2c550 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2c560 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2c570 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2c580 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2c590 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2c5a0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2c5b0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2c5c0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2c5d0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2c5e0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2c5f0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2c600 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2c610 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2c620 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2c630 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2c640 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2c650 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2c660 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2c670 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2c680 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2c690 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2c6a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2c6b0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2c6c0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2c6d0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2c6e0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2c6f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2c700 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2c710 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2c720 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2c730 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2c740 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2c750 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2c760 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2c770 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2c780 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2c790 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2c7a0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2c7b0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2c7c0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2c7d0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2c7e0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2c7f0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2c800 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2c810 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2c820 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2c830 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2c840 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2c850 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2c860 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2c870 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2c880 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2c890 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2c8a0 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2c8b0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2c8c0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2c8d0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2c8e0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2c8f0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2c900 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2c910 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2c920 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2c930 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2c940 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2c950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2c960 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2c970 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2c980 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2c990 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2c9a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2c9b0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2c9c0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2c9d0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2c9e0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2c9f0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2ca00 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2ca10 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2ca20 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2ca30 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2ca40 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2ca50 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2ca60 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2ca70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2ca80 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2ca90 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2caa0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2cab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2cac0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2cad0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2cae0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2caf0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2cb00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2cb10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2cb20 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2cb30 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2cb40 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2cb50 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
2cb60 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2cb70 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
2cb80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2cb90 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2cba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2cbb0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
2cbc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2cbd0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2cbe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2cbf0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
2cc00 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2cc10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2cc20 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2cc30 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2cc40 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2cc50 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2cc60 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2cc70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2cc80 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2cc90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2cca0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
2ccb0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ccc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ccd0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
2cce0 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
2ccf0 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
2cd00 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2cd10 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2cd20 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2cd30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cd40 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2cd50 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2cd60 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2cd70 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2cd80 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2cd90 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2cda0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2cdb0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2cdc0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2cdd0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2cde0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2cdf0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2ce00 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2ce10 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2ce20 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2ce30 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2ce40 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2ce50 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2ce60 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2ce70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ce80 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2ce90 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2cea0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2ceb0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2cec0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2ced0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2cee0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2cef0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2cf00 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2cf10 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2cf20 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2cf30 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2cf40 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2cf50 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2cf60 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2cf70 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2cf80 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2cf90 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2cfa0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2cfb0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2cfc0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2cfd0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2cfe0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2cff0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2d000 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2d010 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2d020 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2d030 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2d040 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2d050 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2d060 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2d070 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2d080 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2d090 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2d0a0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2d0b0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2d0c0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2d0d0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2d0e0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2d0f0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2d100 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2d110 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2d120 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2d130 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2d140 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2d150 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2d160 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
2d170 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2d180 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2d190 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d1a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2d1b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2d1c0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2d1d0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2d1e0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2d1f0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2d200 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
2d210 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2d220 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
2d230 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d240 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
2d250 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
2d260 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2d270 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2d280 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2d290 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
2d2a0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2d2b0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
2d2c0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
2d2d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d2e0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
2d2f0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
2d300 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2d310 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
2d320 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2d330 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
2d340 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
2d350 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
2d360 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
2d370 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
2d380 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
2d390 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
2d3a0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
2d3b0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
2d3c0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
2d3d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2d3e0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2d3f0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
2d400 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
2d410 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
2d420 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2d430 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2d440 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
2d450 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
2d460 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
2d470 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2d480 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
2d490 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
2d4a0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2d4b0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
2d4c0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
2d4d0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
2d4e0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2d4f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2d500 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
2d510 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
2d520 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
2d530 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
2d540 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
2d550 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2d560 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2d570 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
2d580 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
2d590 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
2d5a0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2d5b0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
2d5c0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2d5d0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
2d5e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
2d5f0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
2d600 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
2d610 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
2d620 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
2d630 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
2d640 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
2d650 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
2d660 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
2d670 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
2d680 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
2d690 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2d6a0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
2d6b0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
2d6c0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
2d6d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
2d6e0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
2d6f0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
2d700 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
2d710 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
2d720 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
2d730 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2d740 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
2d750 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
2d760 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
2d770 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
2d780 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
2d790 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
2d7a0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
2d7b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2d7c0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2d7d0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
2d7e0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2d7f0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
2d800 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
2d810 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
2d820 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
2d830 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
2d840 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2d850 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
2d860 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2d870 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
2d880 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
2d890 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
2d8a0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
2d8b0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
2d8c0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
2d8d0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
2d8e0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
2d8f0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
2d900 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
2d910 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
2d920 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2d930 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
2d940 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
2d950 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
2d960 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
2d970 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
2d980 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
2d990 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
2d9a0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
2d9b0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
2d9c0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
2d9d0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
2d9e0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
2d9f0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2da00 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2da10 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
2da20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
2da30 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
2da40 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
2da50 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
2da60 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
2da70 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
2da80 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2da90 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
2daa0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2dab0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
2dac0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
2dad0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
2dae0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
2daf0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
2db00 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2db10 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
2db20 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2db30 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
2db40 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2db50 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
2db60 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2db70 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
2db80 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
2db90 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
2dba0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2dbb0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
2dbc0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
2dbd0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
2dbe0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
2dbf0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
2dc00 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2dc10 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2dc20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
2dc30 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
2dc40 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2dc50 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
2dc60 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
2dc70 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
2dc80 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
2dc90 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
2dca0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
2dcb0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
2dcc0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2dcd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
2dce0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
2dcf0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
2dd00 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
2dd10 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
2dd20 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
2dd30 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2dd40 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
2dd50 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
2dd60 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2dd70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
2dd80 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
2dd90 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2dda0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
2ddb0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
2ddc0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
2ddd0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
2dde0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
2ddf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2de00 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
2de10 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2de20 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
2de30 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2de40 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
2de50 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
2de60 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
2de70 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
2de80 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
2de90 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
2dea0 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
2deb0 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
2dec0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2ded0 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
2dee0 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
2def0 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
2df00 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
2df10 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
2df20 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
2df30 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
2df40 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
2df50 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
2df60 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
2df70 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
2df80 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
2df90 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
2dfa0 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
2dfb0 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
2dfc0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
2dfd0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2dfe0 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
2dff0 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
2e000 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
2e010 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
2e020 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
2e030 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
2e040 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2e050 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
2e060 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
2e070 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
2e080 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
2e090 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2e0a0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
2e0b0 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
2e0c0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
2e0d0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
2e0e0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
2e0f0 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
2e100 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2e110 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e120 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
2e130 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
2e140 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
2e150 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
2e160 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
2e170 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
2e180 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
2e190 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
2e1a0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
2e1b0 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
2e1c0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
2e1d0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
2e1e0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
2e1f0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
2e200 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
2e210 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2e220 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2e230 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e240 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
2e250 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
2e260 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2e270 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2e280 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2e290 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
2e2a0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
2e2b0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2e2c0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
2e2d0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
2e2e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2e2f0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2e300 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2e310 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
2e320 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2e330 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
2e340 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e350 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
2e360 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
2e370 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t set.** METHOD:
2e380 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e390 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e3a0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
2e3b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e3c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2e3d0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
2e3e0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2e3f0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2e400 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2e410 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
2e420 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2e430 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
2e440 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
2e450 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
2e460 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
2e470 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e480 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
2e490 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
2e4a0 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
2e4b0 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
2e4c0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
2e4d0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
2e4e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2e4f0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
2e500 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
2e510 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2e520 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e530 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2e540 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2e550 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
2e560 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2e570 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2e580 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
2e590 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
2e5a0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2e5b0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2e5c0 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
2e5d0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
2e5e0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2e5f0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2e600 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
2e610 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
2e620 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
2e630 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
2e640 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
2e650 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
2e660 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
2e670 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
2e680 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
2e690 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
2e6a0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
2e6b0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2e6c0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
2e6d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
2e6e0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2e6f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2e700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e710 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2e720 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
2e730 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2e740 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
2e750 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
2e760 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
2e770 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
2e780 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
2e790 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
2e7a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2e7b0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
2e7c0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
2e7d0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
2e7e0 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
2e7f0 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
2e800 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
2e810 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2e820 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2e830 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2e840 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2e850 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2e860 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2e870 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2e880 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2e890 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2e8a0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2e8b0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2e8c0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2e8d0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2e8e0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2e8f0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2e900 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2e910 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2e920 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2e930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2e940 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2e950 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2e960 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2e970 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2e980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2e990 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2e9a0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2e9b0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2e9c0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2e9d0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2e9e0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2e9f0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2ea00 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2ea10 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2ea20 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
2ea30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2ea40 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2ea50 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
2ea60 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2ea70 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2ea80 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2ea90 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2eaa0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2eab0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2eac0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2ead0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2eae0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2eaf0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2eb00 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2eb10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2eb20 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2eb30 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2eb40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2eb50 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2eb60 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2eb70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2eb80 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2eb90 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2eba0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2ebb0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2ebc0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2ebd0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2ebe0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2ebf0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2ec00 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2ec10 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2ec20 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2ec30 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2ec40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2ec50 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2ec60 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2ec70 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2ec80 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2ec90 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2eca0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2ecb0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2ecc0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2ecd0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2ece0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2ecf0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2ed00 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2ed10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2ed20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2ed30 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2ed40 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2ed50 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2ed60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ed70 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2ed80 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2ed90 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2eda0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2edb0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2edc0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2edd0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2ede0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2edf0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2ee00 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2ee10 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2ee20 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2ee30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2ee40 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2ee50 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2ee60 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2ee70 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2ee80 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2ee90 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2eea0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2eeb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2eec0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2eed0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2eee0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2eef0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2ef00 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2ef10 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2ef20 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2ef30 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2ef40 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2ef50 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2ef60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ef70 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2ef80 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2ef90 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2efa0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2efb0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2efc0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2efd0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2efe0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2eff0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2f000 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2f010 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2f020 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2f030 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2f040 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2f050 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2f060 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2f070 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2f080 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2f090 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2f0a0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2f0b0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2f0c0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2f0d0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2f0e0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2f0f0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2f100 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2f110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2f120 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2f130 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2f140 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2f150 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2f160 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2f170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2f180 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2f190 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2f1a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2f1b0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2f1c0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2f1d0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2f1e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f1f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2f200 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2f210 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2f220 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2f230 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f240 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2f250 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2f260 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f270 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2f280 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2f290 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2f2a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2f2b0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2f2c0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2f2d0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2f2e0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2f2f0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2f300 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2f310 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2f320 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2f330 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2f340 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2f350 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f360 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2f370 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2f380 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2f390 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f3a0 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2f3b0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2f3c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2f3d0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2f3e0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2f3f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f400 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2f410 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2f420 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f430 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2f440 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2f450 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2f460 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2f470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f480 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2f490 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2f4a0 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2f4b0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2f4c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2f4d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2f4e0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2f4f0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2f500 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f510 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2f520 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2f530 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2f540 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2f550 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2f560 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2f570 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2f580 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2f590 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2f5a0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2f5b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f5c0 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2f5d0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2f5e0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2f5f0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2f600 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2f610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2f620 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2f630 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2f640 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2f650 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2f660 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2f670 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2f680 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2f690 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2f6a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2f6b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2f6c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2f6d0 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2f6e0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2f6f0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2f700 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2f710 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2f720 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2f730 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2f740 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2f750 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f760 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2f770 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2f780 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2f790 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2f7a0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2f7b0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2f7c0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2f7d0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2f7e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2f7f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72  er..**.** <b>War
2f800 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f  ning:</b> ^The o
2f810 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2f820 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2f830 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2f840 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2f850 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2f860 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75  object.  In a mu
2f870 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69  ltithreaded envi
2f880 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75  ronment,.** an u
2f890 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2f8a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
2f8b0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2f8c0 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20   safely with.** 
2f8d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2f8e0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2f8f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2f900 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2f910 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2f920 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2f930 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2f940 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f950 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2f960 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2f970 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2f980 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2f990 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2f9a0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2f9b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f9c0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2f9d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2f9e0 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69  s()], the behavi
2f9f0 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  or is not thread
2fa00 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  safe..**.** Thes
2fa10 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2fa20 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2fa30 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2fa40 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2fa50 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2fa60 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2fa70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2fa80 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2fa90 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2faa0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2fab0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2fac0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2fad0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2fae0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2faf0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2fb00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2fb10 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2fb20 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2fb30 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2fb40 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2fb50 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2fb60 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2fb70 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2fb80 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2fb90 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2fba0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2fbb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2fbc0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2fbd0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2fbe0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2fbf0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2fc00 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2fc10 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2fc20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2fc30 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2fc40 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2fc50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2fc60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2fc70 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2fc80 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2fc90 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2fca0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2fcb0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2fcc0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2fcd0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2fce0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2fcf0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2fd00 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2fd10 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2fd20 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2fd30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2fd40 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2fd50 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2fd60 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2fd70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2fd80 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2fd90 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2fda0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2fdb0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2fdc0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2fdd0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2fde0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2fdf0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2fe00 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2fe10 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2fe20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
2fe30 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2fe40 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2fe50 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2fe60 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2fe70 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2fe80 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2fe90 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2fea0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2feb0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2fec0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2fed0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2fee0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2fef0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2ff00 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2ff10 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2ff20 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2ff30 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2ff40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2ff50 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2ff60 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2ff70 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2ff80 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2ff90 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2ffa0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e  quote>)^.**.** N
2ffb0 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2ffc0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2ffd0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2ffe0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2fff0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
30000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
30010 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
30020 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
30030 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
30040 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
30050 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
30060 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
30070 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
30080 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
30090 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
300a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
300b0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
300c0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
300d0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
300e0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
300f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30100 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
30110 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30120 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
30130 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
30140 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
30150 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
30160 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
30170 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
30180 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
30190 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
301a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
301b0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
301c0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
301d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
301e0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
301f0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
30200 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
30210 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
30220 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
30230 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
30240 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
30250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30260 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
30270 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
30280 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
30290 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
302a0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
302b0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
302c0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
302d0 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
302e0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
302f0 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
30300 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
30310 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
30320 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
30330 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
30340 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
30350 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
30360 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
30370 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
30380 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
30390 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
303a0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
303b0 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
303c0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
303d0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
303e0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
303f0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
30400 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
30410 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
30420 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
30430 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
30440 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
30450 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70  .** The safest p
30460 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
30470 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
30480 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
30490 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
304a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
304b0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
304c0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
304d0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
304e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
304f0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
30500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30510 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
30520 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30530 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
30540 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
30550 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
30560 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
30570 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
30580 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
30590 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
305a0 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
305b0 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
305c0 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
305d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
305e0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
305f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
30600 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
30610 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
30620 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
30630 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
30640 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30650 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
30660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30670 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
30680 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
30690 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
306a0 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
306b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
306c0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
306d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
306e0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
306f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30700 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
30710 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
30720 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30730 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
30740 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
30750 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
30770 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
30780 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
30790 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
307a0 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
307b0 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
307c0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
307d0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
307e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
307f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
30800 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
30810 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
30820 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
30830 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
30840 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
30850 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
30860 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d    Do <em>not</em
30870 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
30880 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
30890 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
308a0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
308b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
308c0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
308d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
308e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
308f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
30900 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
30910 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
30920 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
30930 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
30940 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
30950 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
30960 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
30970 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
30980 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
30990 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
309a0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
309b0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
309c0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
309d0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
309e0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
309f0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
30a00 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
30a10 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
30a20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30a30 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
30a40 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
30a50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30a60 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
30a70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30a80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
30a90 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
30aa0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30ab0 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
30ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
30ad0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30ae0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
30af0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
30b00 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
30b10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
30b20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
30b30 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
30b40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30b50 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
30b60 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
30b70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30b80 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
30b90 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
30ba0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30bb0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
30bc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30bd0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
30be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
30bf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30c00 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
30c10 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
30c20 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
30c30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30c40 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
30c50 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
30c60 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
30c70 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
30c80 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c   DESTRUCTOR: sql
30c90 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30ca0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
30cb0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
30cc0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
30cd0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
30ce0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
30cf0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
30d00 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
30d10 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
30d20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65  encountered no e
30d30 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74  rrors.** or if t
30d40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
30d50 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75  never been evalu
30d60 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74  ated, then sqlit
30d70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65  e3_finalize() re
30d80 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f  turns.** SQLITE_
30d90 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73  OK.  ^If the mos
30da0 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
30db0 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74  ion of statement
30dc0 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a   S failed, then.
30dd0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ** sqlite3_final
30de0 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74  ize(S) returns t
30df0 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  he appropriate [
30e00 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a  error code] or.*
30e10 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  * [extended erro
30e20 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
30e30 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
30e40 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20  lize(S) routine 
30e50 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74  can be called at
30e60 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e   any point durin
30e70 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79  g.** the life cy
30e80 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64  cle of [prepared
30e90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a   statement] S:.*
30ea0 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65  * before stateme
30eb0 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61  nt S is ever eva
30ec0 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a  luated, after.**
30ed0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
30ee0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
30ef0 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65  eset()], or afte
30f00 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f  r any call.** to
30f10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
30f20 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  ] regardless of 
30f30 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
30f40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
30f50 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
30f60 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ecution..**.** ^
30f70 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  Invoking sqlite3
30f80 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61  _finalize() on a
30f90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
30fa0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
30fb0 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  p..**.** The app
30fc0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69  lication must fi
30fd0 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72  nalize every [pr
30fe0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30ff0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76  ] in order to av
31000 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20  oid.** resource 
31010 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20  leaks.  It is a 
31020 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66  grievous error f
31030 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
31040 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65  on to try to use
31050 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73  .** a prepared s
31060 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
31070 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
31080 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f  ized.  Any use o
31090 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  f a prepared.** 
310a0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
310b0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
310c0 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74  lized can result
310d0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
310e0 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  d.** undesirable
310f0 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61   behavior such a
31100 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20  s segfaults and 
31110 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e  heap corruption.
31120 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31130 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
31140 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31160 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
31170 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
31180 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31190 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
311a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
311b0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
311c0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
311d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
311e0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
311f0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
31200 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
31210 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
31220 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
31230 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
31240 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
31250 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
31260 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
31270 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
31280 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
31290 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
312a0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
312b0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
312c0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
312d0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
312e0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
312f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
31300 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
31310 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
31320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31330 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
31340 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
31350 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
31360 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
31370 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
31380 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
31390 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
313a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
313b0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
313c0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
313d0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
313e0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
313f0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
31400 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
31410 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
31420 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
31430 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
31440 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
31450 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
31460 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
31470 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
31480 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
31490 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
314a0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
314b0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
314c0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
314d0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
314e0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
314f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
31500 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
31510 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
31520 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
31530 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
31540 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
31550 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
31560 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
31570 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
31580 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
31590 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
315a0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
315b0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
315c0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
315d0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
315e0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
315f0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
31600 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
31610 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31620 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
31630 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
31640 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31650 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
31660 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
31670 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
31680 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
31690 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
316a0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
316b0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
316c0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
316d0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
316e0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
316f0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
31700 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
31710 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
31720 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
31730 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
31740 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
31750 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
31760 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
31770 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
31780 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
31790 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
317a0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
317b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
317c0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
317d0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
317e0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
317f0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
31800 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
31810 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31820 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
31830 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
31840 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
31850 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31860 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
31870 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
31880 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
31890 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
318a0 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
318b0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
318c0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
318d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
318e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
318f0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
31900 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
31910 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31920 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
31930 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
31940 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
31950 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
31960 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
31970 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
31980 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
31990 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
319a0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
319b0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
319c0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
319d0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
319e0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
319f0 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
31a00 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
31a10 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
31a20 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
31a30 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
31a40 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
31a50 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
31a60 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
31a70 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
31a80 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
31a90 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
31aa0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
31ab0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
31ac0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
31ad0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
31ae0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
31af0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
31b00 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
31b10 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
31b20 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
31b30 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
31b40 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
31b50 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
31b60 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
31b70 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
31b80 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
31b90 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
31ba0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
31bb0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
31bc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
31bd0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
31be0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
31bf0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
31c00 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
31c10 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
31c20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
31c30 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
31c40 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
31c50 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
31c60 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
31c70 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
31c80 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
31c90 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
31ca0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
31cb0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
31cc0 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69  ters.  The appli
31cd0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65  cation should se
31ce0 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  t this parameter
31cf0 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   to.** [SQLITE_U
31d00 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66  TF16LE] if the f
31d10 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
31d20 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a  tation invokes .
31d30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
31d40 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e  e_text16le()] on
31d50 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53   an input, or [S
31d60 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69  QLITE_UTF16BE] i
31d70 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
31d80 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
31d90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31da0 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e  ext16be()] on an
31db0 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53   input, or.** [S
31dc0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20  QLITE_UTF16] if 
31dd0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31de0 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64  ext16()] is used
31df0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
31e00 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e  8].** otherwise.
31e10 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20    ^The same SQL 
31e20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
31e30 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
31e40 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a  ple times using.
31e50 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65  ** different pre
31e60 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
31e70 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66  dings, with diff
31e80 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  erent implementa
31e90 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63  tions for.** eac
31ea0 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e  h encoding..** ^
31eb0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
31ec0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
31ed0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
31ee0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
31ef0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
31f00 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
31f10 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
31f20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
31f30 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
31f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
31f50 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  th parameter may
31f60 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f   optionally be O
31f70 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  Red with [SQLITE
31f80 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a  _DETERMINISTIC].
31f90 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61  ** to signal tha
31fa0 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77  t the function w
31fb0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
31fc0 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c  n the same resul
31fd0 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73  t given.** the s
31fe0 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69  ame inputs withi
31ff0 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  n a single SQL s
32000 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20  tatement.  Most 
32010 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  SQL functions ar
32020 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74  e.** determinist
32030 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69  ic.  The built-i
32040 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c  n [random()] SQL
32050 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20   function is an 
32060 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20  example of a.** 
32070 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73  function that is
32080 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74   not determinist
32090 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ic.  The SQLite 
320a0 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73  query planner is
320b0 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66   able to.** perf
320c0 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f  orm additional o
320d0 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20  ptimizations on 
320e0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75  deterministic fu
320f0 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a  nctions, so use.
32100 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ** of the [SQLIT
32110 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
32120 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65   flag is recomme
32130 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69  nded where possi
32140 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ble..**.** ^(The
32150 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
32160 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
32170 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
32180 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32190 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
321a0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
321b0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
321c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
321d0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
321e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
321f0 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
32200 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
32210 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
32220 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
32230 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
32240 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
32250 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
32260 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32270 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
32280 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
32290 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
322a0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
322b0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
322c0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
322d0 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
322e0 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
322f0 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
32300 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
32310 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
32320 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
32330 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
32340 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32350 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
32360 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
32370 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
32380 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
32390 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
323a0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
323b0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
323c0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
323d0 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
323e0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
323f0 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
32400 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
32410 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
32420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32430 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
32440 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
32450 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
32460 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
32470 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
32480 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
32490 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
324a0 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
324b0 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
324c0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
324d0 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
324e0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
324f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
32500 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
32510 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
32520 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
32530 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
32540 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32550 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
32560 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
32570 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
32580 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
32590 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
325a0 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
325b0 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
325c0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
325d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
325e0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
325f0 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
32600 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
32610 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
32620 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32630 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
32640 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
32650 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
32660 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
32670 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
32680 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
32690 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
326a0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
326b0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
326c0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
326d0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
326e0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
326f0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
32700 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
32710 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
32720 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
32730 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
32740 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
32750 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
32760 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
32770 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
32780 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
32790 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
327a0 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
327b0 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
327c0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
327d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
327e0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
327f0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
32800 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
32810 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
32820 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
32830 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
32840 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
32850 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
32860 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
32870 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
32880 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
32890 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
328a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
328b0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
328c0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
328d0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
328e0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
328f0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
32900 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
32910 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
32920 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
32930 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
32940 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
32950 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
32960 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
32970 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32980 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
32990 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
329a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
329b0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
329c0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
329d0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
329e0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
329f0 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
32a00 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
32a10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32a20 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
32a30 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
32a40 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
32a50 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
32a60 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
32a70 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
32a80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32a90 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
32aa0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
32ab0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
32ac0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
32ad0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
32ae0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
32af0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
32b00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
32b10 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
32b20 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
32b30 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
32b40 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
32b50 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
32b60 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
32b70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
32b80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
32b90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
32ba0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
32bb0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
32bc0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
32bd0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
32be0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
32bf0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
32c00 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
32c10 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32c20 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32c30 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
32c40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
32c50 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
32c60 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
32c70 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
32c80 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
32c90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32ca0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
32cb0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
32cc0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
32cd0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
32ce0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
32cf0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
32d00 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
32d10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32d20 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32d30 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32d40 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
32d50 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32d60 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32d70 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
32d80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32d90 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
32da0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
32db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
32dc0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
32dd0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
32de0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
32df0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
32e00 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
32e10 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
32e20 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
32e30 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
32e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
32e50 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20             1    
32e60 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d  /* IMP: R-37514-
32e70 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65  35566 */.#define
32e80 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
32e90 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49         2    /* I
32ea0 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33  MP: R-03371-3763
32eb0 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  7 */.#define SQL
32ec0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
32ed0 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20     3    /* IMP: 
32ee0 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f  R-51971-34154 */
32ef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32f00 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
32f10 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
32f20 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
32f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
32f40 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
32f50 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64     /* Deprecated
32f60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
32f70 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
32f80 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
32f90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32fa0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
32fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
32fc0 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  tion Flags.**.**
32fd0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
32fe0 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67   may be ORed tog
32ff0 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a  ether with the .
33000 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
33010 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  | preferred text
33020 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68   encoding] as th
33030 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
33040 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
33050 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33060 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
33070 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33080 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
33090 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
330a0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65  on_v2()]..*/.#de
330b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45  fine SQLITE_DETE
330c0 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38  RMINISTIC    0x8
330d0 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
330e0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
330f0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
33100 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
33110 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
33120 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
33130 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
33140 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
33150 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
33160 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
33170 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
33180 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
33190 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
331a0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
331b0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
331c0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
331d0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
331e0 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72  ions.  To encour
331f0 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  age programmers 
33200 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73  to avoid.** thes
33210 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
33220 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e  will not explain
33230 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
33240 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
33250 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
33260 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
33270 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
33280 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
33290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
332a0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
332b0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
332c0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
332d0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
332e0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
332f0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
33300 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
33310 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
33320 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
33330 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
33340 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
33350 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
33360 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
33370 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
33380 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
33390 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
333a0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
333b0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
333c0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
333d0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20  _int64,int),.   
333e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
333f0 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33     void*,sqlite3
33400 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
33410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33420 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56   Obtaining SQL V
33430 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
33440 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
33450 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
33460 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
33470 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
33480 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
33490 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
334a0 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
334b0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
334c0 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
334d0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
334e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
334f0 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a  ggregate.  .**.*
33500 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
33510 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
33520 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
33530 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
33540 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
33550 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33560 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
33570 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33580 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
33590 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
335a0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
335b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
335c0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
335d0 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
335e0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
335f0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
33600 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
33610 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
33620 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33630 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
33640 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
33650 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
33660 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
33670 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
33680 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
33690 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
336a0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
336b0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
336c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
336d0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
336e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
336f0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
33700 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
33710 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
33720 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
33730 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
33740 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
33750 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
33760 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
33770 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
33780 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
33790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
337a0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
337b0 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
337c0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
337d0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
337e0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
337f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
33800 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
33810 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
33820 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
33830 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
33840 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
33850 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
33860 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
33870 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
33880 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33890 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
338a0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
338b0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
338c0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
338d0 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
338e0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
338f0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
33900 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33910 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
33920 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
33930 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
33940 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
33950 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
33960 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
33970 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
33980 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
33990 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
339a0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
339b0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
339c0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
339d0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
339e0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
339f0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
33a00 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
33a10 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
33a20 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
33a30 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
33a40 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
33a50 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
33a60 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
33a70 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
33a80 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
33a90 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
33aa0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
33ab0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
33ac0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
33ad0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
33ae0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
33af0 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
33b00 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
33b10 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
33b20 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
33b30 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
33b40 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
33b50 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
33b60 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
33b70 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
33b80 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
33b90 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
33ba0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
33bb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
33bc0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
33bd0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
33be0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
33bf0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
33c00 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
33c10 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
33c20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
33c30 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
33c40 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
33c50 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
33c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33c70 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
33c80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33c90 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
33ca0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
33cb0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
33cc0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
33cd0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
33ce0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
33cf0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
33d00 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
33d10 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
33d20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
33d30 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
33d40 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
33d50 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
33d60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33d70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
33d80 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
33d90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
33da0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
33db0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
33dc0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
33dd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
33de0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33df0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
33e00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
33e10 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
33e20 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
33e30 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
33e40 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
33e50 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
33e60 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33e70 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
33e80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
33e90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33ea0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
33eb0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
33ec0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
33ed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33ee0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
33ef0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
33f00 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
33f10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
33f20 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
33f30 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
33f40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
33f50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33f60 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51  Copy And Free SQ
33f70 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
33f80 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
33f90 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
33fa0 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
33fb0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
33fc0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
33fd0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
33fe0 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20  ** object D and 
33ff0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
34000 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20  r to that copy. 
34010 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76   ^The [sqlite3_v
34020 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a  alue] returned.*
34030 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65  * is a [protecte
34040 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34050 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20   object even if 
34060 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74  the input is not
34070 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
34080 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
34090 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
340a0 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55   NULL if V is NU
340b0 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65  LL or if a.** me
340c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
340d0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fails..**.** ^Th
340e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
340f0 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63  free(V) interfac
34100 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69  e frees an [sqli
34110 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34120 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  t.** previously 
34130 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
34140 71 6c 69 74 65 5f 76 61 6c 75 65 5f 64 75 70 28  qlite_value_dup(
34150 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20  )].  ^If V is a 
34160 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
34170 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  then sqlite3_val
34180 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61 20  ue_free(V) is a 
34190 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
341a0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
341b0 4d 45 4e 54 41 4c 20 73 71 6c 69 74 65 33 5f 76  MENTAL sqlite3_v
341c0 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61  alue *sqlite3_va
341d0 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71  lue_dup(const sq
341e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
341f0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
34200 41 4c 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  AL void sqlite3_
34210 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74  value_free(sqlit
34220 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
34230 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
34240 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
34250 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
34260 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34270 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
34280 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
34290 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
342a0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
342b0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
342c0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
342d0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
342e0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
342f0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
34300 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
34310 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
34320 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
34330 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
34340 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
34350 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
34360 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
34370 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
34380 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
34390 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
343a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
343b0 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
343c0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
343d0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
343e0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
343f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
34400 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
34410 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
34420 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
34430 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
34440 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
34450 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
34460 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
34470 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
34480 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
34490 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
344a0 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
344b0 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
344c0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
344d0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
344e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
344f0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
34500 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
34510 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
34520 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
34530 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
34540 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
34550 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
34560 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
34570 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
34580 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
34590 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
345a0 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
345b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
345c0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
345d0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
345e0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
345f0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
34600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34610 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34620 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
34630 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
34640 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
34650 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
34660 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
34670 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
34680 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
34690 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
346a0 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
346b0 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
346c0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
346d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
346e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
346f0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
34700 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
34710 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
34720 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
34730 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
34740 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
34750 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
34760 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
34770 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
34780 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
34790 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
347a0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
347b0 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
347c0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
347d0 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
347e0 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
347f0 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
34800 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
34810 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
34820 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
34830 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
34840 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
34850 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
34860 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
34870 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
34880 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
34890 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
348a0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
348b0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
348c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
348d0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
348e0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
348f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
34900 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
34910 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
34920 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
34930 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
34940 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
34950 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
34960 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
34970 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
34980 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
34990 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
349a0 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
349b0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
349c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
349d0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
349e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
349f0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
34a00 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
34a10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
34a20 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
34a30 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
34a40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
34a50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
34a60 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
34a70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
34a80 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
34a90 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
34aa0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
34ab0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34ac0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
34ad0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34ae0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
34af0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
34b00 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
34b10 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
34b20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
34b30 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
34b40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34b50 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
34b60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34b70 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
34b80 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
34b90 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
34ba0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34bb0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
34bc0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
34bd0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
34be0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
34bf0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
34c00 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
34c10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34c20 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
34c30 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
34c40 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
34c50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
34c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34c70 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
34c80 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
34c90 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
34ca0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
34cb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34cc0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
34cd0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
34ce0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
34cf0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
34d00 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
34d10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
34d20 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
34d30 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
34d40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34d50 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
34d60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34d70 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
34d80 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
34d90 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
34da0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
34db0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
34dc0 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
34dd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
34de0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
34df0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
34e00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34e10 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
34e20 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f  ry Data.** METHO
34e30 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
34e40 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  xt.**.** These f
34e50 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
34e60 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67  used by (non-agg
34e70 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63  regate) SQL func
34e80 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
34e90 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
34ea0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
34eb0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
34ec0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
34ed0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
34ee0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
34ef0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
34f00 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
34f10 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
34f20 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
34f30 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
34f40 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
34f50 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
34f60 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a  d.  An example.*
34f70 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20  * of where this 
34f80 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20  might be useful 
34f90 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d  is in a regular-
34fa0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
34fb0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ing.** function.
34fc0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
34fd0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
34fe0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
34ff0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73  can be stored as
35000 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
35010 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
35020 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e   pattern string.
35030 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f    .** Then as lo
35040 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72  ng as the patter
35050 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73  n string remains
35060 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68   the same,.** th
35070 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
35080 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
35090 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
350a0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
350b0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
350c0 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  me function..**.
350d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
350e0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
350f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35100 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
35110 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
35120 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
35130 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35140 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
35150 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
35160 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
35170 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35180 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35190 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e  . ^If there is n
351a0 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  o metadata.** as
351b0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
351c0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  e function argum
351d0 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65  ent, this sqlite
351e0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
351f0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
35200 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
35210 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
35220 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35230 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74  ata(C,N,P,X) int
35240 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61  erface saves P a
35250 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  s metadata for t
35260 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
35270 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
35280 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35290 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65  unction.  ^Subse
352a0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
352b0 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
352c0 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72  xdata(C,N) retur
352d0 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73  n P from the mos
352e0 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69  t recent.** sqli
352f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35300 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66  C,N,P,X) call if
35310 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
35320 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a   still valid or.
35330 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d  ** NULL if the m
35340 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
35350 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e   discarded..** ^
35360 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20  After each call 
35370 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
35380 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
35390 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e  where X is not N
353a0 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ULL,.** SQLite w
353b0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
353c0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
353d0 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65  on X with parame
353e0 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a  ter P exactly.**
353f0 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20   once, when the 
35400 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63  metadata is disc
35410 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  arded..** SQLite
35420 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63   is free to disc
35430 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61  ard the metadata
35440 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e   at any time, in
35450 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a  cluding: <ul>.**
35460 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63   <li> when the c
35470 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
35480 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
35490 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c  changes, or.** <
354a0 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  li> when [sqlite
354b0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
354c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
354d0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  )] is called for
354e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c   the.**      SQL
354f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a   statement, or.*
35500 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69  * <li> when sqli
35510 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35520 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61  ) is invoked aga
35530 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70  in on the same p
35540 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20  arameter, or.** 
35550 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20  <li> during the 
35560 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33  original sqlite3
35570 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63  _set_auxdata() c
35580 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72  all when a memor
35590 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63  y .**      alloc
355a0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
355b0 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  rs. </ul>)^.**.*
355c0 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20  * Note the last 
355d0 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63  bullet in partic
355e0 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72  ular.  The destr
355f0 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73  uctor X in .** s
35600 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35610 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68  ta(C,N,P,X) migh
35620 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65  t be called imme
35630 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20  diately, before 
35640 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  the.** sqlite3_s
35650 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
35660 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75  erface even retu
35670 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69  rns.  Hence sqli
35680 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35690 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63  ).** should be c
356a0 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65  alled near the e
356b0 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nd of the functi
356c0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
356d0 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e  n and the.** fun
356e0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
356f0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
35700 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20  make any use of 
35710 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74  P after.** sqlit
35720 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
35730 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
35740 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
35750 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
35760 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
35770 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
35780 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74  lls for.** funct
35790 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ion parameters t
357a0 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d  hat are compile-
357b0 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20  time constants, 
357c0 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61  including litera
357d0 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
357e0 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64  [parameters] and
357f0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d   expressions com
35800 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73  posed from the s
35810 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ame.)^.**.** The
35820 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
35830 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
35840 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
35850 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
35860 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
35870 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
35880 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
35890 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
358a0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
358b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
358c0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
358d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
358e0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
358f0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
35900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
35910 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
35920 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
35930 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
35940 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
35950 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
35960 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
35970 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
35980 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
35990 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
359a0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
359b0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
359c0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
359d0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
359e0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
359f0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
35a00 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
35a10 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
35a20 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
35a30 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
35a40 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
35a50 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
35a60 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
35a70 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
35a80 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
35a90 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
35aa0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
35ab0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
35ac0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
35ad0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
35ae0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
35af0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
35b00 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
35b10 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
35b20 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
35b30 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
35b40 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
35b50 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
35b60 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65  mpilers..*/.type
35b70 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
35b80 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
35b90 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
35ba0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
35bb0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
35bc0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
35bd0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
35be0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
35bf0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
35c00 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
35c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
35c20 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
35c30 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
35c40 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ion.** METHOD: s
35c50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
35c60 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
35c70 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
35c80 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
35c90 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
35ca0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
35cb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
35cc0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
35cd0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
35ce0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
35cf0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
35d00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
35d10 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
35d20 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
35d30 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
35d40 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
35d50 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
35d60 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
35d70 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
35d80 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
35d90 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
35da0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
35db0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
35dc0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
35dd0 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
35de0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
35df0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
35e00 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
35e10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
35e20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
35e30 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
35e40 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
35e50 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
35e60 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35e70 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
35e80 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
35e90 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
35ea0 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
35eb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
35ec0 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
35ed0 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
35ee0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
35ef0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
35f00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35f10 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
35f20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
35f30 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
35f40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35f50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35f60 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
35f70 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
35f80 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
35f90 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
35fa0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
35fb0 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
35fc0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
35fd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35fe0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
35ff0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
36000 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
36010 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
36020 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36030 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
36040 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
36050 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
36060 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
36070 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36080 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
36090 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
360a0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
360b0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
360c0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
360d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
360e0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
360f0 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ion..** ^SQLite 
36100 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
36110 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
36120 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
36130 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
36140 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
36150 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36160 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
36170 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
36180 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53  ror message.  ^S
36190 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
361a0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
361b0 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
361c0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
361d0 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
361e0 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  8. ^SQLite.** in
361f0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
36200 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
36210 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
36220 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
36230 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
36240 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68  der.  ^If the th
36250 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
36260 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36270 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
36280 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36290 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
362a0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
362b0 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
362c0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
362d0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
362e0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
362f0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
36300 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
36310 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
36320 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
36330 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
36340 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
36350 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
36360 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
36370 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
36380 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
36390 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
363a0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
363b0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
363c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
363d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
363e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
363f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
36400 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
36410 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
36420 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
36430 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
36440 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
36450 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
36460 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
36470 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
36480 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
36490 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
364a0 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
364b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
364c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
364d0 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68  de() function ch
364e0 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20  anges the error 
364f0 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  code.** returned
36500 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20   by SQLite as a 
36510 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72  result of an err
36520 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e  or in a function
36530 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a  .  ^By default,.
36540 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
36550 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
36560 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e  R.  ^A subsequen
36570 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
36580 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
36590 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
365a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
365b0 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72  resets the error
365c0 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f   code to SQLITE_
365d0 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ERROR..**.** ^Th
365e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
365f0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20  _error_toobig() 
36600 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
36610 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
36620 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
36630 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
36640 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
36650 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
36660 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
36670 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36680 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20  t_error_nomem() 
36690 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
366a0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
366b0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64   an.** error ind
366c0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
366d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
366e0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
366f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36700 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
36710 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
36720 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
36730 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36740 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36750 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
36760 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
36770 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
36780 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
36790 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
367a0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
367b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
367c0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
367d0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
367e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
367f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36800 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
36810 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
36820 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
36830 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
36840 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36850 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
36860 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36870 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36880 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
36890 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
368a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
368b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
368c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
368d0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
368e0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
368f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36900 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
36910 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36920 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
36930 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
36940 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
36950 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36960 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36970 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
36980 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
36990 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
369a0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
369b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
369c0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
369d0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
369e0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
369f0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
36a00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36a10 75 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74  ult_text64() int
36a20 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
36a30 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
36a40 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  an.** applicatio
36a50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36a60 6f 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74 20  on to be a text 
36a70 73 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63  string in an enc
36a80 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69  oding.** specifi
36a90 65 64 20 62 79 20 74 68 65 20 66 69 66 74 68 20  ed by the fifth 
36aa0 28 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d  (and last) param
36ab0 65 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74  eter, which must
36ac0 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53   be one.** of [S
36ad0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
36ae0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
36af0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
36b00 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
36b10 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  E]..** ^SQLite t
36b20 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
36b30 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
36b40 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
36b50 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
36b60 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
36b70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
36b80 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
36b90 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
36ba0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
36bb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
36bc0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
36bd0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
36be0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
36bf0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
36c00 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
36c10 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
36c20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
36c30 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
36c40 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
36c50 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
36c60 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
36c70 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
36c80 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
36c90 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
36ca0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
36cb0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
36cc0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
36cd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
36ce0 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
36cf0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36d00 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
36d10 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
36d20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
36d30 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
36d40 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
36d50 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
36d60 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
36d70 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
36d80 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
36d90 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
36da0 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
36db0 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
36dc0 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
36dd0 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
36de0 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
36df0 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
36e00 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
36e10 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
36e20 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
36e30 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
36e40 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
36e50 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
36e60 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
36e70 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
36e80 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
36e90 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
36ea0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
36eb0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
36ec0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
36ed0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
36ee0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36ef0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
36f00 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
36f10 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
36f20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
36f30 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
36f40 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
36f50 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
36f60 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
36f70 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
36f80 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
36f90 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
36fa0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
36fb0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
36fc0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
36fd0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
36fe0 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
36ff0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
37000 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
37010 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
37020 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
37030 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
37040 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
37050 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
37060 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
37070 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
37080 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
37090 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
370a0 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
370b0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
370c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
370d0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
370e0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
370f0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
37100 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
37110 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
37120 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
37130 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
37140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
37150 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
37160 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
37170 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
37180 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
37190 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
371a0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
371b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
371c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
371d0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
371e0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
371f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37200 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
37210 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37220 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
37230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
37240 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
37250 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
37260 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
37270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
37280 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
37290 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
372a0 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
372b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
372c0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
372d0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
372e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
372f0 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
37300 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
37310 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
37320 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
37330 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
37340 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
37350 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
37360 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
37370 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
37380 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
37390 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
373a0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
373b0 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
373c0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
373d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
373e0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
373f0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
37400 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
37410 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37420 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
37430 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
37440 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
37450 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
37460 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
37470 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
37480 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
37490 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
374a0 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
374b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
374c0 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
374d0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
374e0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
374f0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
37500 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
37510 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
37520 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
37530 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37540 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
37550 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37560 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37570 75 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74  ult_blob64(sqlit
37580 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73  e3_context*,cons
37590 74 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20  t void*,.       
375a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
375b0 20 20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74      sqlite3_uint
375c0 36 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  64,void(*)(void*
375d0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
375e0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
375f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37600 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
37610 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37620 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
37630 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
37640 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
37650 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37660 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
37670 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
37680 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
37690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
376a0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
376b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
376c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
376d0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
376e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
376f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37700 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
37710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37720 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
37730 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
37740 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37750 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
37760 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
37770 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
37780 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
37790 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
377a0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
377b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
377c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
377d0 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
377e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
377f0 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
37800 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
37810 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37820 74 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  t_text64(sqlite3
37830 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
37840 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
37850 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
37860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37870 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
37880 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  , unsigned char 
37890 65 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20  encoding);.void 
378a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
378b0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
378c0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
378d0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
378e0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
378f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37900 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
37910 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37920 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
37930 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37940 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37950 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
37960 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
37970 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
37980 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
37990 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
379a0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
379b0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
379c0 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
379d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
379e0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
379f0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
37a00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37a10 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
37a20 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
37a30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37a40 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
37a50 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
37a60 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
37a70 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
37a80 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
37a90 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
37aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
37ab0 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
37ac0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
37ad0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
37ae0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
37af0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
37b00 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
37b10 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37b20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
37b30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37b40 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
37b50 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
37b60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37b70 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
37b80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
37b90 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
37ba0 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
37bb0 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
37bc0 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
37bd0 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
37be0 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
37bf0 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
37c00 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
37c10 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
37c20 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
37c30 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
37c40 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
37c50 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
37c60 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
37c70 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
37c80 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
37c90 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
37ca0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
37cb0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
37cc0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
37cd0 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
37ce0 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
37cf0 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
37d00 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
37d10 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
37d20 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
37d30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37d40 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
37d50 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
37d60 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
37d70 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
37d80 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
37d90 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
37da0 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
37db0 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
37dc0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
37dd0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
37de0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
37df0 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
37e00 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
37e10 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
37e20 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
37e30 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
37e40 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
37e50 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
37e60 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
37e70 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
37e80 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
37e90 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
37ea0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
37eb0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37ec0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
37ed0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
37ee0 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
37ef0 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
37f00 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
37f10 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
37f20 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
37f30 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
37f40 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
37f50 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
37f60 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
37f70 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
37f80 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
37f90 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
37fa0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
37fb0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
37fc0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
37fd0 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
37fe0 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
37ff0 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
38000 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
38010 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
38020 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
38030 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
38040 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
38050 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
38060 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
38070 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
38080 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
38090 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
380a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
380b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
380c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
380d0 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
380e0 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
380f0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
38100 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
38110 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
38120 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
38130 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
38140 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
38150 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
38160 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
38170 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
38180 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
38190 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
381a0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
381b0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
381c0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
381d0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
381e0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
381f0 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
38200 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
38210 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
38220 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
38230 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
38240 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
38250 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
38260 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
38270 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
38280 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
38290 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
382a0 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
382b0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
382c0 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
382d0 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
382e0 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
382f0 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
38300 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
38310 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
38320 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
38330 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
38340 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
38350 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
38360 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
38370 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
38380 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
38390 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
383a0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
383b0 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
383c0 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
383d0 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
383e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
383f0 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
38400 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
38410 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
38420 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
38430 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
38440 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
38450 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
38460 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
38470 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
38480 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
38490 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
384a0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
384b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
384c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
384d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
384e0 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
384f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
38500 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
38510 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
38520 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
38530 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
38540 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
38550 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
38560 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
38570 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
38580 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
38590 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
385a0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
385b0 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
385c0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
385d0 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
385e0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
385f0 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
38600 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38610 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
38620 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
38630 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
38640 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
38650 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
38660 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
38670 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38680 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
38690 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
386a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
386b0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
386c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
386d0 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
386e0 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
386f0 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
38700 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
38710 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
38720 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
38730 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
38740 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
38750 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
38760 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
38770 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
38780 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
38790 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
387a0 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
387b0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
387c0 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
387d0 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
387e0 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
387f0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
38800 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
38810 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .**