/ Hex Artifact Content
Login

Artifact 495d16a58094ca33960fcf0eedf9fe2174f05629:


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 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b7b0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
b7c0: 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CK]].** The [SQL
b7d0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
b7e0: 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c  OCK] is a signal
b7f0: 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65   to the VFS laye
b800: 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a  r that it might.
b810: 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f  ** be advantageo
b820: 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74  us to block on t
b830: 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b  he next WAL lock
b840: 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20   if the lock is 
b850: 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  not immediately.
b860: 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54  ** available.  T
b870: 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d  he WAL subsystem
b880: 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67   issues this sig
b890: 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a  nal during rare.
b8a0: 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  ** circumstances
b8b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78   in order to fix
b8c0: 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20   a problem with 
b8d0: 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69  priority inversi
b8e0: 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  on..** Applicati
b8f0: 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e  ons should <em>n
b900: 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73  ot</em> use this
b910: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a   file-control..*
b920: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
b930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b940: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
b950: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
b960: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b970: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
b980: 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66  ILE       2.#def
b990: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b9a0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
b9b0: 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  LE       3.#defi
b9c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b9d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
b9e0: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
b9f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
ba00: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
ba10: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
ba20: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
ba30: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
ba40: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
ba50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
ba60: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
ba70: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
ba80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
ba90: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
baa0: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
bab0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
bac0: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
bad0: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
bae0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
baf0: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
bb00: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
bb10: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
bb20: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
bb30: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
bb40: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
bb50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
bb60: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
bb70: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
bb80: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
bb90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bba0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
bbb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
bbc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bbd0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
bbe0: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
bbf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bc00: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
bc10: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
bc20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc30: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
bc40: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
bc50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc60: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
bc70: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
bc80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bc90: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
bca0: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
bcb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bcc0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
bcd0: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
bce0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
bcf0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
bd00: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65        22.#define
bd10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
bd20: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20  N32_SET_HANDLE  
bd30: 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20       23.#define 
bd40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
bd50: 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  _BLOCK          
bd60: 20 20 20 20 32 34 0a 0a 2f 2a 20 64 65 70 72 65      24../* depre
bd70: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
bd80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
bd90: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
bda0: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
bdb0: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
bdc0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
bdd0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
bde0: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
bdf0: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
be00: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
be10: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
be20: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
be30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
be40: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
be50: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
be60: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
be70: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
be80: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
be90: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
bea0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
beb0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
bec0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
bed0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
bee0: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
bef0: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
bf00: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
bf10: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
bf20: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
bf30: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
bf40: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
bf50: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
bf60: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
bf70: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
bf80: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
bf90: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
bfa0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
bfb0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
bfc0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
bfd0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
bfe0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
bff0: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
c000: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
c010: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
c020: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
c030: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
c040: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
c050: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
c060: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
c070: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
c080: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
c090: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
c0a0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
c0b0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
c0c0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
c0d0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
c0e0: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
c0f0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
c100: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
c110: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
c120: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
c130: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
c140: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
c150: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
c160: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
c170: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
c180: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
c190: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
c1a0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
c1b0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
c1c0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
c1d0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
c1e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
c1f0: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
c200: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
c210: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
c220: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
c230: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
c240: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
c250: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
c260: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
c270: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
c280: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
c290: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
c2a0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
c2b0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
c2c0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
c2d0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
c2e0: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
c2f0: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
c300: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
c310: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
c320: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
c330: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
c340: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
c350: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
c360: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
c370: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
c380: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
c390: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
c3a0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
c3b0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
c3c0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
c3d0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
c3e0: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
c3f0: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
c400: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
c410: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
c420: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
c430: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
c440: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
c450: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
c460: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
c470: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
c480: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
c490: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
c4a0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
c4b0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
c4c0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c4d0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
c4e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
c4f0: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
c500: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
c510: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
c520: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
c530: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
c540: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c550: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
c560: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
c570: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
c580: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
c590: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
c5a0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
c5b0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
c5c0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
c5d0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
c5e0: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
c5f0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
c600: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
c610: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
c620: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
c630: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
c640: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
c650: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
c660: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c670: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
c680: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
c690: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
c6a0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
c6b0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
c6c0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
c6d0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
c6e0: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
c6f0: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
c700: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
c710: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
c720: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
c730: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
c740: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
c750: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
c760: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
c770: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
c780: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
c790: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c7a0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
c7b0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
c7c0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
c7d0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
c7e0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
c7f0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
c800: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
c810: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c820: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
c830: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
c840: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
c850: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
c860: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
c870: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
c880: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
c890: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c8a0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
c8b0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
c8c0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
c8d0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
c8e0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
c8f0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
c900: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
c910: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c920: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
c930: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
c940: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
c950: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
c960: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
c970: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c980: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
c990: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
c9a0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
c9b0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
c9c0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
c9d0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
c9e0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
c9f0: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
ca00: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
ca10: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
ca20: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
ca30: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
ca40: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
ca50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ca60: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
ca70: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
ca80: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
ca90: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
caa0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
cab0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
cac0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
cad0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
cae0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
caf0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
cb00: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
cb10: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
cb20: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
cb30: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
cb40: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
cb50: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
cb60: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
cb70: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
cb80: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
cb90: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
cba0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
cbb0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
cbc0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
cbd0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cbe0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
cbf0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cc00: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
cc10: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cc20: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
cc30: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
cc40: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
cc50: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cc60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
cc70: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
cc80: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cc90: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
cca0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
ccb0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
ccc0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
ccd0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
cce0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
ccf0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
cd00: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
cd10: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
cd20: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
cd30: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
cd40: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
cd50: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
cd60: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
cd70: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
cd80: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
cd90: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
cda0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
cdb0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
cdc0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
cdd0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
cde0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
cdf0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
ce00: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
ce10: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
ce20: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
ce30: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
ce40: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
ce50: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
ce60: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
ce70: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
ce80: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
ce90: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
cea0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
ceb0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
cec0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
ced0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
cee0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
cef0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
cf00: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
cf10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
cf20: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
cf30: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
cf40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
cf50: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
cf60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
cf70: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
cf80: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
cf90: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
cfa0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
cfb0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
cfc0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
cfd0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
cfe0: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
cff0: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
d000: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
d010: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
d020: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
d030: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
d040: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
d050: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
d060: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
d070: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
d080: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
d090: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
d0a0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
d0b0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
d0c0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
d0d0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
d0e0: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
d0f0: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
d100: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
d110: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d120: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
d130: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
d140: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
d150: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
d160: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
d170: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
d180: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
d190: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
d1a0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
d1b0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
d1c0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
d1d0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
d1e0: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
d1f0: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
d200: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
d210: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
d220: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
d230: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
d240: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
d250: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
d260: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
d270: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
d280: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
d290: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
d2a0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
d2b0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
d2c0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
d2d0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
d2e0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
d2f0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
d300: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
d310: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
d320: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
d330: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
d340: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
d350: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
d360: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d370: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
d380: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
d390: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
d3a0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
d3b0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
d3c0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
d3d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
d3e0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
d3f0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
d400: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
d410: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
d420: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
d430: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
d440: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
d450: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
d460: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
d470: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d480: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
d490: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
d4a0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
d4b0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
d4c0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
d4d0: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
d4e0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
d4f0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
d500: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
d510: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
d520: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
d530: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
d540: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
d550: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
d560: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
d570: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
d580: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
d590: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
d5a0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
d5b0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
d5c0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
d5d0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
d5e0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
d5f0: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
d600: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
d610: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d620: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
d630: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
d640: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
d650: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d660: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
d670: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
d680: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
d690: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
d6a0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
d6b0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
d6c0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
d6d0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
d6e0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
d6f0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
d700: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
d710: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
d720: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
d730: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
d740: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
d750: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
d760: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
d770: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
d780: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
d790: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d7a0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
d7b0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
d7c0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
d7d0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
d7e0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
d7f0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
d800: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
d810: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
d820: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
d830: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
d840: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
d850: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
d860: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
d870: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
d880: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
d890: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
d8a0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
d8b0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
d8c0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
d8d0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
d8e0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
d8f0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
d900: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
d910: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
d920: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
d930: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
d940: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
d950: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
d960: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
d970: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
d980: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
d990: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
d9a0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
d9b0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
d9c0: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
d9d0: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
d9e0: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
d9f0: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
da00: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
da10: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
da20: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
da30: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
da40: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
da50: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
da60: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
da70: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
da80: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
da90: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
daa0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
dab0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
dac0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
dad0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
dae0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
daf0: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
db00: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
db10: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
db20: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
db30: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
db40: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
db50: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
db60: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
db70: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
db80: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
db90: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
dba0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
dbb0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
dbc0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
dbd0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
dbe0: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
dbf0: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
dc00: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
dc10: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
dc20: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
dc30: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
dc40: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
dc50: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
dc60: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
dc70: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
dc80: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
dc90: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
dca0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
dcb0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
dcc0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
dcd0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
dce0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
dcf0: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
dd00: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
dd10: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
dd20: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
dd30: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
dd40: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
dd50: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
dd60: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
dd70: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
dd80: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
dd90: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
dda0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
ddb0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
ddc0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
ddd0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
dde0: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
ddf0: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
de00: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
de10: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
de20: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
de30: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
de40: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
de50: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
de60: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
de70: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
de80: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
de90: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
dea0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
deb0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
dec0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
ded0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
dee0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
def0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
df00: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
df10: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
df20: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
df30: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
df40: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
df50: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
df60: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
df70: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
df80: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
df90: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
dfa0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
dfb0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
dfc0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
dfd0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
dfe0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
dff0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
e000: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
e010: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
e020: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
e030: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
e040: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
e050: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
e060: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
e070: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e080: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e090: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
e0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
e0b0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e0c0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
e0d0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
e0e0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e0f0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e100: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
e110: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
e120: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e130: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e140: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
e150: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
e160: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
e170: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e180: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e190: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
e1a0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
e1b0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
e1c0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e1d0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
e1e0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
e1f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e200: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
e210: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
e220: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
e230: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
e240: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
e250: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
e260: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
e270: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e280: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
e290: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
e2a0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
e2b0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
e2c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
e2d0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
e2e0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
e2f0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
e300: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
e310: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
e320: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
e330: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
e340: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
e350: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
e360: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e370: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
e380: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
e390: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
e3a0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
e3b0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
e3c0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
e3d0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
e3e0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
e3f0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
e400: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
e410: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
e420: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e430: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e440: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
e450: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
e460: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e470: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
e480: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
e490: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
e4a0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
e4b0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e4c0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e4d0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e4e0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
e4f0: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
e500: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
e510: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e520: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e530: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
e540: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
e550: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e560: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e570: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
e580: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e590: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e5a0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
e5b0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
e5c0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
e5d0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
e5e0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
e5f0: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
e600: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
e610: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
e620: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
e630: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
e640: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
e650: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
e660: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
e670: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
e680: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e690: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
e6a0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
e6b0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
e6c0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
e6d0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
e6e0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
e6f0: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
e700: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
e710: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
e720: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e730: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
e740: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
e750: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
e760: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e770: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
e780: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
e790: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
e7a0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
e7b0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
e7c0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e7d0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
e7e0: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
e7f0: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
e800: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
e810: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
e820: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
e830: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
e840: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
e850: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
e860: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
e870: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
e880: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
e890: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
e8a0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
e8b0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
e8c0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
e8d0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
e8e0: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
e8f0: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
e900: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
e910: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
e920: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
e930: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e940: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
e950: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
e960: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
e970: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e980: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
e990: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
e9a0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
e9b0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
e9c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
e9d0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
e9e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
e9f0: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
ea00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ea10: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ea20: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
ea30: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
ea40: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
ea50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ea60: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
ea70: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
ea80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ea90: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
eaa0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
eab0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
eac0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
ead0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
eae0: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
eaf0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
eb00: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
eb10: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
eb20: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
eb30: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
eb40: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
eb50: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
eb60: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
eb70: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
eb80: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
eb90: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
eba0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
ebb0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
ebc0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
ebd0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
ebe0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
ebf0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
ec00: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
ec10: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
ec20: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ec30: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
ec40: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ec50: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ec60: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
ec70: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
ec80: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
ec90: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
eca0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
ecb0: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
ecc0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
ecd0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
ece0: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
ecf0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
ed00: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
ed10: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
ed20: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
ed30: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
ed40: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
ed50: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
ed60: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
ed70: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
ed80: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
ed90: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
eda0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
edb0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
edc0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
edd0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
ede0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
edf0: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
ee00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
ee10: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
ee20: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
ee30: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
ee40: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
ee50: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
ee60: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
ee70: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
ee80: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
ee90: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
eea0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
eeb0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
eec0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
eed0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
eee0: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
eef0: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
ef00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ef10: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
ef20: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
ef30: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
ef40: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
ef50: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
ef60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ef70: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
ef80: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
ef90: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
efa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
efb0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
efc0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
efd0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
efe0: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
eff0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
f000: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
f010: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
f020: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
f030: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
f040: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
f050: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
f060: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
f070: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
f080: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
f090: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
f0a0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
f0b0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
f0c0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
f0d0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
f0e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f0f0: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
f100: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
f110: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
f120: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f130: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f140: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
f150: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
f160: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
f170: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
f180: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f190: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f1a0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
f1b0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
f1c0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f1d0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
f1e0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
f1f0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
f200: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
f210: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
f220: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
f230: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
f240: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
f250: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
f260: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f270: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
f280: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
f290: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
f2a0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
f2b0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
f2c0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
f2d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
f2e0: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
f2f0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
f300: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f310: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
f320: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
f330: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
f340: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
f350: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
f360: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
f370: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
f380: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f390: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
f3a0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
f3b0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f3c0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
f3d0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f3e0: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
f3f0: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
f400: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
f410: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
f420: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
f430: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
f440: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
f450: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
f460: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
f470: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
f480: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
f490: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
f4a0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
f4b0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
f4c0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
f4d0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
f4e0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f4f0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
f500: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
f510: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
f520: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
f530: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
f540: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f550: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f560: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
f570: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f580: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
f590: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
f5a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f5b0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
f5c0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
f5d0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
f5e0: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
f5f0: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
f600: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
f610: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
f620: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
f630: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
f640: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
f650: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
f660: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f670: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
f680: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
f690: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
f6a0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
f6b0: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
f6c0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
f6d0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
f6e0: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
f6f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f700: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
f710: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
f720: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
f730: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
f740: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
f750: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
f760: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
f770: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
f780: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
f790: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
f7a0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
f7b0: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
f7c0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
f7d0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
f7e0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f7f0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
f800: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
f810: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
f820: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
f830: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
f840: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
f850: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
f860: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
f870: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
f880: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
f890: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
f8a0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
f8b0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
f8c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
f8d0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
f8e0: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
f8f0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
f900: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
f910: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
f920: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f930: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
f940: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
f950: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
f960: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
f970: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
f980: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
f990: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
f9a0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
f9b0: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
f9c0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
f9d0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f9e0: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
f9f0: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
fa00: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
fa10: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
fa20: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
fa30: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
fa40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fa50: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
fa60: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
fa70: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
fa80: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
fa90: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
faa0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
fab0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
fac0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
fad0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
fae0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
faf0: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
fb00: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
fb10: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
fb20: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
fb30: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
fb40: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
fb50: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
fb60: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
fb70: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
fb80: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
fb90: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
fba0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
fbb0: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
fbc0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
fbd0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
fbe0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fbf0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
fc00: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
fc10: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
fc20: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
fc30: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
fc40: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
fc50: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
fc60: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
fc70: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
fc80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fc90: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
fca0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
fcb0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
fcc0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
fcd0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
fce0: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
fcf0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fd00: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
fd10: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
fd20: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
fd30: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
fd40: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
fd50: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
fd60: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
fd70: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
fd80: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
fd90: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
fda0: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
fdb0: 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
fdc0: 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
fdd0: 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
fde0: 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
fdf0: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
fe00: 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
fe10: 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
fe20: 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
fe30: 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
fe40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
fe50: 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
fe60: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
fe70: 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
fe80: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
fe90: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
fea0: 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
feb0: 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
fec0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
fed0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fee0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
fef0: 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
ff00: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
ff10: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
ff20: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
ff30: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
ff40: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
ff50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ff60: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
ff70: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
ff80: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
ff90: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
ffa0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
ffb0: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
ffc0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
ffd0: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
ffe0: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
fff0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10000 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10010 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
10020 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
10030 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10040 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
10050 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
10060 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
10070 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
10080 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
10090 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
100a0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
100b0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
100c0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
100d0 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
100e0 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
100f0 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
10100 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
10110 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
10120 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
10130 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
10140 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
10150 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10160 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
10170 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20  hreadsafe.  The 
10180 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
10190 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
101a0 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
101b0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
101c0 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
101d0 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
101e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
101f0 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46  ) is running.  F
10200 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69  urthermore, sqli
10210 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20  te3_config().** 
10220 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
10230 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
10240 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
10250 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
10260 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10270 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
10280 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
10290 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
102a0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
102b0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
102c0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
102d0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
102e0 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
102f0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10300 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
10310 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
10320 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
10330 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
10340 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
10350 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
10360 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
10370 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
10380 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
10390 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
103a0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
103b0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
103c0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
103d0 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
103e0 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
103f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
10400 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
10410 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
10420 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
10430 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
10440 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10450 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
10460 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
10470 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10480 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10490 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
104a0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
104b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
104c0 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
104d0 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
104e0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
104f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
10500 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
10510 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
10520 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
10530 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
10540 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10550 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
10560 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
10570 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10580 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
10590 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
105a0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
105b0 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
105c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
105d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
105e0 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
105f0 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
10600 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
10610 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10620 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
10630 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
10640 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
10650 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
10660 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
10670 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
10680 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
10690 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
106a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
106b0 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
106c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
106d0 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
106e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
106f0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10700 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
10710 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
10720 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10730 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
10740 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
10750 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
10760 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
10770 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
10780 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10790 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
107a0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
107b0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
107c0 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
107d0 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
107e0 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
107f0 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
10800 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10810 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
10820 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
10830 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
10840 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
10850 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
10860 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10870 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
10880 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
10890 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
108a0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
108b0 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
108c0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
108d0 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
108e0 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
108f0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
10900 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
10910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
10920 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
10930 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
10940 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
10950 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
10960 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
10970 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
10980 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
10990 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
109a0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
109b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
109c0 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
109d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
109e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
109f0 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
10a00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
10a10 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
10a20 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
10a30 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
10a40 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
10a50 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
10a60 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
10a70 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10a80 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
10a90 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
10aa0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
10ab0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
10ac0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
10ad0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
10ae0 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
10af0 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
10b00 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
10b10 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
10b20 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
10b30 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
10b40 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
10b50 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
10b60 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
10b70 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
10b80 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
10b90 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
10ba0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
10bb0 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
10bc0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
10bd0 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
10be0 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
10bf0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
10c00 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
10c10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10c20 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
10c30 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
10c40 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
10c50 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
10c60 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
10c70 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
10c80 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
10c90 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
10ca0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
10cb0 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
10cc0 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
10cd0 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
10ce0 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
10cf0 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
10d00 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
10d10 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
10d20 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
10d30 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
10d40 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
10d50 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
10d60 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
10d70 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
10d80 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
10d90 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
10da0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
10db0 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
10dc0 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
10dd0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
10de0 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
10df0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10e00 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
10e10 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
10e20 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
10e30 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
10e40 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
10e50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10e60 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
10e70 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
10e80 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
10e90 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
10ea0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
10eb0 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
10ec0 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
10ed0 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
10ee0 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
10ef0 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
10f00 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
10f10 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
10f20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
10f30 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
10f40 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
10f50 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
10f60 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
10f70 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
10f80 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
10f90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10fa0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
10fb0 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
10fc0 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
10fd0 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
10fe0 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
10ff0 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
11000 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
11010 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
11020 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
11030 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
11040 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
11050 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
11060 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
11070 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
11080 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
11090 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
110a0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
110b0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
110c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
110d0 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
110e0 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
110f0 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
11100 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11110 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
11120 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
11130 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
11140 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
11150 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
11160 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
11170 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
11180 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
11190 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
111a0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
111b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
111c0 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
111d0 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
111e0 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
111f0 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
11200 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
11210 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
11220 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
11230 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
11240 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
11250 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
11260 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11270 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
11280 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
11290 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
112a0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
112b0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
112c0 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
112d0 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
112e0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
112f0 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
11300 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11310 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
11320 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
11330 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
11340 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
11350 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
11360 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
11370 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11380 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
11390 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
113a0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
113b0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
113c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
113d0 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
113e0 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
113f0 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
11400 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
11410 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
11420 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
11430 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
11440 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11450 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
11460 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
11470 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
11480 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
11490 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
114a0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
114b0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
114c0 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
114d0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
114e0 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
114f0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
11500 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
11510 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
11520 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
11530 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
11540 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11550 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
11560 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
11570 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11580 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
11590 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
115a0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
115b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
115c0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
115d0 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
115e0 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
115f0 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
11600 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
11610 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
11620 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
11630 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
11640 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
11650 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11660 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
11670 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
11680 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
11690 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
116a0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
116b0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
116c0 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
116d0 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
116e0 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
116f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
11700 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
11710 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
11720 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
11730 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
11740 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
11750 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
11760 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
11770 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
11780 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
11790 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
117a0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
117b0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
117c0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
117d0 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
117e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
117f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11800 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
11810 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
11820 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
11830 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
11840 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
11850 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
11860 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
11870 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
11880 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
11890 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
118a0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
118b0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
118c0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
118d0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
118e0 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
118f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11900 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
11910 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
11920 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
11930 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
11940 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
11950 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11960 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
11970 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
11980 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
11990 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
119a0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
119b0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
119c0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
119d0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
119e0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
119f0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
11a00 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
11a10 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
11a20 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
11a30 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11a40 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
11a50 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
11a60 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
11a70 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11a80 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11a90 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11aa0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11ab0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11ac0 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
11ad0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
11ae0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
11af0 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
11b00 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
11b10 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
11b20 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
11b30 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
11b40 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
11b50 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
11b60 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
11b70 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
11b80 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11b90 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11ba0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11bb0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
11bc0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
11bd0 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
11be0 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
11bf0 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
11c00 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
11c10 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
11c20 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11c30 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
11c40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11c50 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
11c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11c70 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
11c80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11c90 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
11ca0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11cb0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
11cc0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11cd0 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
11ce0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
11cf0 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
11d00 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
11d10 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
11d20 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
11d30 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
11d40 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
11d50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
11d60 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
11d70 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
11d80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
11d90 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11da0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
11db0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
11dc0 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
11dd0 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
11de0 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
11df0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11e00 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
11e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
11e20 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
11e30 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
11e40 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
11e50 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
11e60 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
11e70 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
11e80 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
11e90 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
11ea0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
11eb0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
11ec0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11ed0 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
11ee0 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
11ef0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11f00 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11f10 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11f20 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11f30 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11f40 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11f50 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11f60 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
11f70 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
11f80 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
11f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
11fa0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
11fb0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
11fc0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
11fd0 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
11fe0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
11ff0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12000 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12010 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12020 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
12030 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12040 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
12050 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
12060 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
12070 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
12080 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
12090 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
120a0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
120b0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
120c0 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
120d0 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
120e0 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
120f0 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
12100 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
12110 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
12120 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
12130 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12140 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
12150 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
12160 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
12170 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
12180 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12190 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
121a0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
121b0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
121c0 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
121d0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
121e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
121f0 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
12200 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
12210 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
12220 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
12230 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
12240 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12250 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
12260 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
12270 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
12280 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
12290 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
122a0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
122b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
122c0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
122d0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
122e0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
122f0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12300 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12310 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12320 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
12330 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
12340 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
12350 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12360 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12370 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12380 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12390 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
123a0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
123b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
123c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
123d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
123e0 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
123f0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
12400 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12410 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12420 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
12430 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12440 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
12450 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
12460 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12470 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12480 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12490 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
124a0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
124b0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
124c0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
124d0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
124e0 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
124f0 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
12500 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12510 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
12520 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12530 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
12540 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
12550 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
12560 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
12570 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12580 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
12590 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
125a0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
125b0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
125c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
125d0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
125e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
125f0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
12600 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
12610 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
12620 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
12630 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12640 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
12650 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12660 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
12670 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
12680 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12690 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
126a0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
126b0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
126c0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
126d0 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
126e0 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
126f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
12700 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
12710 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
12720 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
12730 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
12740 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
12750 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
12760 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
12770 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
12780 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
12790 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
127a0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
127b0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
127c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
127d0 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
127e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
127f0 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
12800 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
12810 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12820 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
12830 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12840 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
12850 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
12860 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
12870 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
12880 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
12890 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
128a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
128b0 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
128c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
128d0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
128e0 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
128f0 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
12900 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
12910 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
12920 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
12930 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12940 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
12950 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12960 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
12970 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
12980 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
12990 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
129a0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
129b0 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
129c0 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
129d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
129e0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
129f0 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
12a00 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
12a10 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
12a20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
12a30 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
12a40 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
12a50 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
12a60 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12a70 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
12a80 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
12a90 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12aa0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
12ab0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12ac0 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
12ad0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
12ae0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12af0 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  TCH option speci
12b00 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
12b10 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
12b20 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
12b30 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d  se for scratch m
12b40 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20  emory.  ^(There 
12b50 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12b60 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45  nts.** to SQLITE
12b70 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a  _CONFIG_SCRATCH:
12b80 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
12b90 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
12ba0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
12bb0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
12bc0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
12bd0 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
12be0 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
12bf0 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
12c00 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
12c10 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
12c20 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
12c30 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
12c40 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72  N).)^.** The fir
12c50 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
12c60 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
12c70 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
12c80 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
12c90 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
12ca0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
12cb0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
12cc0 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e  ot use more than
12cd0 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
12ce0 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e  fers per thread.
12cf0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
12d00 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61   never request a
12d10 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
12d20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
12d30 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
12d40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
12d50 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ize..** ^If SQLi
12d60 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
12d70 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
12d80 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
12d90 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
12da0 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
12db0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12dc0 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
12dd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
12de0 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
12df0 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
12e00 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57  needed.<p>.** ^W
12e10 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74  hen the applicat
12e20 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79  ion provides any
12e30 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74   amount of scrat
12e40 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a  ch memory using.
12e50 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12e60 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65  _SCRATCH, SQLite
12e70 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73   avoids unnecess
12e80 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71  ary large.** [sq
12e90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61  lite3_malloc|hea
12ea0 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a  p allocations]..
12eb0 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70  ** This can help
12ec0 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70   [Robson proof|p
12ed0 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c  revent memory al
12ee0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
12ef0 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a  s] due to heap.*
12f00 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  * fragmentation 
12f10 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d  in low-memory em
12f20 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a  bedded systems..
12f30 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
12f40 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
12f50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
12f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
12f70 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
12f80 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
12f90 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
12fa0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
12fb0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
12fc0 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  y buffer.** that
12fd0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
12fe0 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
12ff0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
13000 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
13010 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
13020 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
13030 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
13040 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
13050 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
13060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
13070 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
13080 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
13090 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
130a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
130b0 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69  CACHE2].** confi
130c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
130d0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
130e0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
130f0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
13100 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
13110 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
13120 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
13130 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
13140 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
13150 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
13160 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
13170 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
13180 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
13190 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
131a0 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
131b0 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
131c0 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
131d0 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36  en 512 and 65536
131e0 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72  ) plus some extr
131f0 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68  a bytes for each
13200 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
13210 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66    ^The number of
13220 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65   extra bytes nee
13230 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20  ded by the page 
13240 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65  header.** can be
13250 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
13260 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
13270 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
13280 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f  Z] option .** to
13290 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
132a0 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68  ()]..** ^It is h
132b0 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
132c0 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
132d0 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68  emory,.** for th
132e0 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74  e sz parameter t
132f0 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  o be larger than
13300 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65   necessary.  The
13310 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
13320 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65  nt should pointe
13330 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
13340 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20  ligned block of 
13350 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69  memory that.** i
13360 73 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  s at least sz*N 
13370 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c  bytes of memory,
13380 20 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 65   otherwise subse
13390 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69  quent behavior i
133a0 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
133b0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
133c0 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
133d0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
133e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
133f0 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
13400 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
13410 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
13420 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
13430 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61  to cache.  ^If a
13440 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
13450 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
13460 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
13470 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
13480 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
13490 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
134a0 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
134b0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
134c0 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
134d0 6f 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 64  orage space.</dd
134e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
134f0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
13500 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13510 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
13520 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
13530 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
13540 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
13550 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
13560 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  er .** that SQLi
13570 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20  te will use for 
13580 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
13590 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
135a0 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65  tion needs.** be
135b0 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
135c0 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  ded for by [SQLI
135d0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
135e0 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54  H] and.** [SQLIT
135f0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13600 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  HE]..** ^The SQL
13610 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
13620 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
13630 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
13640 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  te is compiled.*
13650 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53  * with either [S
13660 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
13670 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45  SYS3] or [SQLITE
13680 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
13690 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
136a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
136b0 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77  f invoked otherw
136c0 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  ise..** ^There a
136d0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
136e0 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
136f0 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20  FIG_HEAP:.** An 
13700 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
13710 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
13720 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
13730 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
13740 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
13750 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
13760 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
13770 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
13780 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
13790 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
137a0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
137b0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
137c0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
137d0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
137e0 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
137f0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
13800 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
13810 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
13820 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
13830 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13840 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
13850 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
13860 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
13870 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
13880 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
13890 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
138a0 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
138b0 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
138c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
138d0 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
138e0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
138f0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
13900 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
13910 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
13920 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
13930 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
13940 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
13950 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
13960 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
13970 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
13980 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
13990 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
139a0 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
139b0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
139c0 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
139d0 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
139e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
139f0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
13a00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13a10 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
13a20 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
13a30 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70  _CONFIG_MUTEX op
13a40 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13a50 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13a60 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  ch is a.** point
13a70 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
13a80 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
13a90 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
13aa0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
13ab0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
13ac0 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76  ifies alternativ
13ad0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
13ae0 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
13af0 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63   used.** in plac
13b00 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  e the mutex rout
13b10 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
13b20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
13b30 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
13b40 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
13b50 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
13b60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
13b70 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
13b80 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
13b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13ba0 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
13bb0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13bc0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
13bd0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13be0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13bf0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13c00 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13c10 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
13c20 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
13c30 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
13c40 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
13c50 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
13c60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13c70 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
13c80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13c90 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
13ca0 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
13cb0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13cc0 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
13cd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13ce0 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
13cf0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13d00 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
13d10 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13d20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
13d30 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
13d40 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13d50 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
13d60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13d70 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13d80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13d90 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13da0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
13db0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
13dc0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
13dd0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
13de0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
13df0 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
13e00 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
13e10 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
13e20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
13e30 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
13e40 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
13e50 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
13e60 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
13e70 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
13e80 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
13e90 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
13ea0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
13eb0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
13ec0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13ed0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13ee0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13ef0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13f00 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13f10 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
13f20 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
13f30 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
13f40 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
13f50 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
13f60 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
13f70 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13f80 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13f90 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
13fa0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13fb0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
13fc0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13fd0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13fe0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
13ff0 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
14000 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14010 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
14020 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14030 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14040 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  E option takes t
14050 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
14060 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74  t determine.** t
14070 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20  he default size 
14080 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  of lookaside mem
14090 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74  ory on each [dat
140a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
140b0 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  ]..** The first 
140c0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
140d0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
140e0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
140f0 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
14100 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
14110 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
14120 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
14130 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14140 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54  tion.)^  ^(SQLIT
14150 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14160 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c  DE.** sets the <
14170 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
14180 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
14190 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
141a0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
141b0 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69   option to [sqli
141c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
141d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
141e0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
141f0 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
14200 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
14210 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
14220 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
14230 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14240 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
14250 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14260 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
14270 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
14280 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
14290 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
142a0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
142b0 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65   is .** a pointe
142c0 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33  r to an [sqlite3
142d0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
142e0 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
142f0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
14300 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63  .** the interfac
14310 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  e to a custom pa
14320 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
14330 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53  ntation.)^.** ^S
14340 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
14350 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
14360 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
14370 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e  s2] object.</dd>
14380 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14390 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
143a0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
143b0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
143c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
143d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
143e0 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74  G_GETPCACHE2 opt
143f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14400 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14410 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
14420 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33  r to an [sqlite3
14430 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14440 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
14450 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74  e copies of.** t
14460 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20  he current page 
14470 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
14480 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
14490 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
144a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
144b0 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
144c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
144d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68  </dt>.** <dd> Th
144e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
144f0 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  LOG option is us
14500 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
14510 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c  the SQLite.** gl
14520 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d  obal [error log]
14530 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54  ..** (^The SQLIT
14540 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
14550 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
14560 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
14570 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
14580 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
14590 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
145a0 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
145b0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
145c0 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
145d0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
145e0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
145f0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
14600 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
14610 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
14620 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
14630 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
14640 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
14650 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
14660 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
14670 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
14680 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
14690 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
146a0 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
146b0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
146c0 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
146d0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
146e0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
146f0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
14700 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
14710 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14720 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14730 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
14740 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
14750 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
14760 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14770 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
14780 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
14790 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
147a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
147b0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
147c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
147d0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
147e0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
147f0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
14800 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
14810 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
14820 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
14830 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
14840 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
14850 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
14860 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
14870 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
14880 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
14890 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
148a0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
148b0 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
148c0 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
148d0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
148e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
148f0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
14900 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
14910 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
14920 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
14930 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
14940 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
14950 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
14960 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
14970 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
14980 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14990 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
149a0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
149b0 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45  <dd>^(The SQLITE
149c0 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69  _CONFIG_URI opti
149d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
149e0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
149f0 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f  pe int..** If no
14a00 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  n-zero, then URI
14a10 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14a20 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49  bally enabled. I
14a30 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
14a40 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  is zero,.** then
14a50 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14a60 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
14a70 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61  ed.)^ ^If URI ha
14a80 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
14a90 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61  ly.** enabled, a
14aa0 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73  ll filenames pas
14ab0 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
14ac0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
14ad0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a  3_open_v2()],.**
14ae0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
14af0 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
14b00 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
14b10 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
14b20 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
14b30 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
14b40 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
14b50 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
14b60 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
14b70 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
14b80 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
14b90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
14ba0 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73  pened. ^If it is
14bb0 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
14bc0 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
14bd0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
14be0 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
14bf0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
14c00 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
14c10 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
14c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14c30 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79   is opened. ^(By
14c40 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
14c50 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
14c60 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
14c70 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
14c80 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
14c90 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
14ca0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
14cb0 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
14cc0 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a  l defined.)^.**.
14cd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14ce0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14cf0 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c  X_SCAN]] <dt>SQL
14d00 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14d10 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a  ING_INDEX_SCAN.*
14d20 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
14d30 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
14d40 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74  G_INDEX_SCAN opt
14d50 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14d60 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72  le integer.** ar
14d70 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
14d80 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
14d90 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
14da0 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
14db0 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73  isable.** the us
14dc0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14dd0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
14de0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
14df0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
14e00 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  r..** ^The defau
14e10 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65  lt setting is de
14e20 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
14e30 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57  he [SQLITE_ALLOW
14e40 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14e50 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SCAN] compile-ti
14e60 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73  me option, or is
14e70 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74   "on".** if that
14e80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14e90 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e  tion is omitted.
14ea0 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20  .** The ability 
14eb0 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  to disable the u
14ec0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
14ed0 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
14ee0 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69  table scans.** i
14ef0 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69  s because some i
14f00 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64  ncorrectly coded
14f10 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74   legacy applicat
14f20 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75  ions might malfu
14f30 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74  nction.** when t
14f40 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14f50 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
14f60 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
14f70 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
14f80 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
14f90 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
14fa0 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
14fb0 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
14fc0 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
14fd0 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
14fe0 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
14ff0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
15000 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15010 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
15020 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15030 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15040 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
15050 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
15060 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
15070 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
15080 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
15090 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
150a0 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
150b0 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
150c0 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
150d0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
150e0 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
150f0 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  no-ops..** </dd>
15100 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15110 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
15120 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
15130 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
15140 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
15150 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
15160 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
15170 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
15180 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
15190 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72  E_SQLLOG] pre-pr
151a0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
151b0 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74  fined. The first
151c0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
151d0 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72  .** be a pointer
151e0 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
151f0 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76  f type void(*)(v
15200 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f  oid*,sqlite3*,co
15210 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e  nst char*, int).
15220 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73  .** The second s
15230 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65  hould be of type
15240 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61   (void*). The ca
15250 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
15260 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79  d by the library
15270 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70  .** in three sep
15280 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e  arate circumstan
15290 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20  ces, identified 
152a0 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73  by the value pas
152b0 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f  sed as the.** fo
152c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20  urth parameter. 
152d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
152e0 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68  rameter is 0, th
152f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
15300 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61  connection.** pa
15310 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
15320 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  nd argument has 
15330 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64  just been opened
15340 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  . The third argu
15350 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  ment.** points t
15360 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61  o a buffer conta
15370 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f  ining the name o
15380 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  f the main datab
15390 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65  ase file. If the
153a0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
153b0 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20  eter is 1, then 
153c0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
153d0 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64  t that the third
153e0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f   parameter.** po
153f0 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74  ints to has just
15400 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20   been executed. 
15410 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74  Or, if the fourt
15420 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32  h parameter is 2
15430 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  , then.** the co
15440 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70  nnection being p
15450 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15460 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
15470 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54   being closed. T
15480 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
15490 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20  meter is passed 
154a0 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73  NULL In this cas
154b0 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f  e.  An example o
154c0 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20  f using this.** 
154d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
154e0 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e  tion can be seen
154f0 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71   in the "test_sq
15500 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66  llog.c" source f
15510 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61  ile in.** the ca
15520 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73  nonical SQLite s
15530 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e  ource tree.</dd>
15540 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15550 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
15560 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15570 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15580 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45  E.** <dd>^SQLITE
15590 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
155a0 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62  E takes two 64-b
155b0 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69  it integer (sqli
155c0 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65  te3_int64) value
155d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68  s.** that are th
155e0 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73  e default mmap s
155f0 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64  ize limit (the d
15600 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66  efault setting f
15610 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d  or.** [PRAGMA mm
15620 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68  ap_size]) and th
15630 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15640 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  d mmap size limi
15650 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  t..** ^The defau
15660 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62  lt setting can b
15670 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
15680 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
15690 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  nnection using.*
156a0 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52  * either the [PR
156b0 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20  AGMA mmap_size] 
156c0 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75  command, or by u
156d0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
156e0 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
156f0 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
15700 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75  l.  ^(The maximu
15710 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
15720 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  ize.** will be s
15730 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
15740 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73  d if necessary s
15750 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e  o that it does n
15760 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ot exceed the.**
15770 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61   compile-time ma
15780 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20  ximum mmap size 
15790 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
157a0 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53  QLITE_MAX_MMAP_S
157b0 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  IZE] compile-tim
157c0 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  e option.)^.** ^
157d0 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65  If either argume
157e0 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  nt to this optio
157f0 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  n is negative, t
15800 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e  hen that argumen
15810 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20  t is.** changed 
15820 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74  to its compile-t
15830 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a  ime default..**.
15840 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15850 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15860 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15870 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
15880 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e  EAPSIZE.** <dd>^
15890 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
158a0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
158b0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
158c0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
158d0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
158e0 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77  ed for Windows w
158f0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
15900 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72  WIN32_MALLOC] pr
15910 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
15920 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53  o.** defined. ^S
15930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15940 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65  32_HEAPSIZE take
15950 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67  s a 32-bit unsig
15960 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ned integer valu
15970 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66  e.** that specif
15980 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  ies the maximum 
15990 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61  size of the crea
159a0 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20  ted heap..**.** 
159b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
159c0 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a  PCACHE_HDRSZ]].*
159d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
159e0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
159f0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15a00 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15a10 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74  E_HDRSZ option t
15a20 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
15a30 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
15a40 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
15a50 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20   an integer and 
15a60 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74  writes into that
15a70 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d   integer the num
15a80 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20  ber of extra.** 
15a90 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72  bytes per page r
15aa0 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68  equired for each
15ab0 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45   page in [SQLITE
15ac0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
15ad0 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e  E]..** The amoun
15ae0 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65  t of extra space
15af0 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68   required can ch
15b00 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f  ange depending o
15b10 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a  n the compiler,.
15b20 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f  ** target platfo
15b30 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76  rm, and SQLite v
15b40 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  ersion..**.** [[
15b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
15b60 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  ASZ]].** <dt>SQL
15b70 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
15b80 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15b90 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
15ba0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15bb0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
15bc0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20   which.** is an 
15bd0 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
15be0 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d   and sets the "M
15bf0 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22  inimum PMA Size"
15c00 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68   for the multith
15c10 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72  readed.** sorter
15c20 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72   to that integer
15c30 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d  .  The default m
15c40 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20  inimum PMA Size 
15c50 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  is set by the.**
15c60 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f   [SQLITE_SORTER_
15c70 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74  PMASZ] compile-t
15c80 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77  ime option.  New
15c90 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75   threads are lau
15ca0 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70  nched.** to help
15cb0 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61   with sort opera
15cc0 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69  tions when multi
15cd0 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67  threaded sorting
15ce0 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28  .** is enabled (
15cf0 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  using the [PRAGM
15d00 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61  A threads] comma
15d10 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75  nd) and the amou
15d20 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a  nt of content.**
15d30 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78   to be sorted ex
15d40 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73  ceeds the page s
15d50 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69  ize times the mi
15d60 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20  nimum of the.** 
15d70 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69  [PRAGMA cache_si
15d80 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20  ze] setting and 
15d90 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c  this value..** <
15da0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
15db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
15dc0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
15dd0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15de0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15df0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
15e00 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15e10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15e20 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
15e30 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15e40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15e50 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
15e60 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
15e70 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
15e80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15e90 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
15ea0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
15eb0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
15ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15ed0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
15ee0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
15ef0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
15f00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15f10 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15f20 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
15f30 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
15f40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15f50 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
15f60 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
15f70 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
15f80 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
15f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15fa0 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
15fb0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
15fc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15fd0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
15fe0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
15ff0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
16000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16010 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
16020 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
16030 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16040 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
16050 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
16060 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
16070 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
16080 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
16090 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
160a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
160b0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
160c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
160d0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
160e0 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
160f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16100 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
16110 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
16120 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
16130 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
16140 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
16150 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
16160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16170 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
16180 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
16190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
161a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
161b0 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
161c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
161d0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
161e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
161f0 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
16200 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
16210 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
16220 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16230 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16240 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
16250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16260 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
16270 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
16280 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
16290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
162a0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
162b0 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
162c0 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
162d0 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
162e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
162f0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
16300 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
16310 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Byte */.#define 
16320 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16330 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20  ACHE_HDRSZ      
16340 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73    24  /* int *ps
16350 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  z */.#define SQL
16360 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
16370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
16380 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69  5  /* unsigned i
16390 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a  nt szPma */../*.
163a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
163b0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
163c0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
163d0 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
163e0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
163f0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
16400 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
16410 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
16420 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
16430 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16440 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
16450 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
16460 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
16470 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
16480 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16490 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
164a0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
164b0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
164c0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
164d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
164e0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
164f0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
16500 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
16510 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
16520 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
16530 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
16540 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
16550 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
16560 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
16570 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
16580 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
16590 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
165a0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
165b0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
165c0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
165d0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
165e0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
165f0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
16600 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
16610 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16620 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
16630 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
16640 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
16650 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
16660 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
16670 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
16680 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
16690 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
166a0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
166b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
166c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
166d0 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
166e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
166f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16700 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
16710 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
16720 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
16730 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
16740 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
16750 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
16760 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
16770 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
16780 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
16790 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
167a0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
167b0 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
167c0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
167d0 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
167e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
167f0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
16800 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
16810 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
16820 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
16830 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
16840 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
16850 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
16860 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
16870 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
16880 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16890 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
168a0 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
168b0 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
168c0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
168d0 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
168e0 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
168f0 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
16900 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
16910 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
16920 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16930 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
16940 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16950 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
16960 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
16970 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
16980 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
16990 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
169a0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
169b0 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
169c0 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
169d0 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
169e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
169f0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
16a00 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
16a10 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
16a20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
16a30 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
16a40 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
16a50 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
16a60 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
16a70 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
16a80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
16a90 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
16aa0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16ab0 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
16ac0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
16ad0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
16ae0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
16af0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
16b00 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
16b10 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
16b20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
16b30 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
16b40 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
16b50 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
16b60 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
16b70 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
16b80 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
16b90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16ba0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
16bb0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
16bc0 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
16bd0 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
16be0 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
16bf0 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
16c00 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
16c10 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
16c20 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
16c30 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
16c40 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
16c50 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
16c60 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
16c70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
16c80 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16c90 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
16ca0 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
16cb0 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
16cc0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
16cd0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
16ce0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
16cf0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
16d00 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
16d10 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
16d20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
16d30 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
16d40 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
16d50 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
16d60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16d70 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
16d80 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
16d90 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
16da0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
16db0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
16dc0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
16dd0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
16de0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16df0 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
16e00 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
16e10 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
16e20 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
16e30 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
16e40 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
16e50 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
16e60 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
16e70 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
16e80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16e90 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
16ea0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
16eb0 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
16ec0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
16ed0 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
16ee0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
16ef0 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
16f00 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
16f10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16f20 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
16f30 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
16f40 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
16f50 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
16f60 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
16f70 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
16f80 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
16f90 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
16fa0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
16fb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16fc0 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
16fd0 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
16fe0 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
16ff0 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
17000 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
17010 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  . </dd>.**.** </
17020 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
17030 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17040 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31  OOKASIDE       1
17050 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
17060 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
17070 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
17080 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
17090 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e   1002  /* int in
170a0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
170b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
170c0 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30  ABLE_TRIGGER  10
170d0 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  03  /* int int* 
170e0 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
170f0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
17100 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
17110 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
17120 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
17130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
17140 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
17150 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
17160 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
17170 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
17180 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
17190 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
171a0 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
171b0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
171c0 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
171d0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
171e0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
171f0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
17200 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
17210 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
17220 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
17230 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
17240 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
17250 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45  sert Rowid.** ME
17260 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
17270 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
17280 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
17290 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
172a0 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
172b0 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
172c0 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
172d0 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
172e0 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
172f0 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
17300 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
17310 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
17320 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
17330 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
17340 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
17350 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
17360 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
17370 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
17380 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
17390 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
173a0 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
173b0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
173c0 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
173d0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
173e0 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
173f0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
17400 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
17410 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
17420 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
17430 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
17440 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
17450 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
17460 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
17470 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
17480 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
17490 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
174a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
174b0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
174c0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
174d0 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
174e0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
174f0 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
17500 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
17510 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17520 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
17530 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
17540 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
17550 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17560 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
17570 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
17580 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
17590 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
175a0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
175b0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
175c0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
175d0 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
175e0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
175f0 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
17600 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
17610 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
17620 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
17630 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
17640 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
17650 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
17660 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
17670 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
17680 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
17690 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
176a0 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
176b0 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
176c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
176d0 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
176e0 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
176f0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
17700 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
17710 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
17720 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
17730 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
17740 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
17750 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
17760 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
17770 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
17780 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
17790 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
177a0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
177b0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
177c0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
177d0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
177e0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
177f0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
17800 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
17810 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
17820 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
17830 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
17840 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
17850 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
17860 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
17870 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
17880 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
17890 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
178a0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
178b0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
178c0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
178d0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
178e0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
178f0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
17900 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
17910 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
17920 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
17930 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
17940 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
17950 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
17960 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
17970 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
17980 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
17990 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
179a0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
179b0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
179c0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
179d0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
179e0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
179f0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
17a00 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
17a10 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
17a20 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
17a30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
17a40 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
17a50 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
17a60 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
17a70 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
17a80 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
17a90 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
17aa0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
17ab0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
17ac0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
17ad0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
17ae0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
17af0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
17b00 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
17b10 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
17b20 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17b30 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
17b40 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
17b50 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
17b60 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
17b70 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
17b80 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
17b90 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
17ba0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
17bb0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17bc0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17bd0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
17be0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
17bf0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17c00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
17c10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
17c20 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
17c30 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
17c40 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
17c50 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
17c60 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
17c70 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
17c80 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
17c90 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
17ca0 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
17cb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17cc0 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
17cd0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
17ce0 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
17cf0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
17d00 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
17d10 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
17d20 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
17d30 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
17d40 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
17d50 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
17d60 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
17d70 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
17d80 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
17d90 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
17da0 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
17db0 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
17dc0 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
17dd0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
17de0 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
17df0 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
17e00 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
17e10 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
17e20 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
17e30 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
17e40 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
17e50 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
17e60 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
17e70 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
17e80 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
17e90 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
17ea0 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
17eb0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
17ec0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
17ed0 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
17ee0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
17ef0 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
17f00 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
17f10 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
17f20 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
17f30 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
17f40 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
17f50 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
17f60 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
17f70 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
17f80 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
17f90 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
17fa0 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
17fb0 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
17fc0 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
17fd0 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
17fe0 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
17ff0 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
18000 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
18010 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
18020 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
18030 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
18040 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
18050 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
18060 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
18070 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
18080 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
18090 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
180a0 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
180b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
180c0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
180d0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
180e0 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
180f0 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
18100 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
18110 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
18120 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
18130 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
18140 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
18150 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
18160 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
18170 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
18180 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
18190 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
181a0 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
181b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
181c0 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
181d0 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
181e0 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
181f0 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
18200 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
18210 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
18220 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
18230 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
18240 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
18250 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18260 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
18270 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
18280 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
18290 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
182a0 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
182b0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
182c0 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
182d0 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
182e0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
182f0 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
18300 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
18310 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
18320 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
18330 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
18340 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
18350 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
18360 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
18370 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
18380 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
18390 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
183a0 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
183b0 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
183c0 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
183d0 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
183e0 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
183f0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18400 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
18410 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
18420 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
18430 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
18440 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
18450 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
18460 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
18470 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
18480 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
18490 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
184a0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
184b0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
184c0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
184d0 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
184e0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
184f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
18500 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
18510 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
18520 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
18530 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
18540 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
18550 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
18560 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
18570 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
18580 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
18590 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
185a0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
185b0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
185c0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
185d0 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
185e0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
185f0 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
18600 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
18610 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
18620 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
18630 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73  mber of rows ins
18640 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20  erted, modified 
18650 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
18660 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   all [INSERT], [
18670 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
18680 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63  TE] statements c
18690 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63  ompleted.** sinc
186a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
186b0 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70  onnection was op
186c0 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ened, including 
186d0 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61  those executed a
186e0 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69  s.** part of tri
186f0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e  gger programs. ^
18700 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
18710 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
18720 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65  statement.** doe
18730 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65  s not affect the
18740 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18750 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
18760 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a  _changes()..** .
18770 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65  ** ^Changes made
18780 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72   as part of [for
18790 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
187a0 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  ] are included i
187b0 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20  n the.** count, 
187c0 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61  but those made a
187d0 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43  s part of REPLAC
187e0 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
187f0 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e  olution are.** n
18800 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  ot. ^Changes to 
18810 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
18820 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49  intercepted by I
18830 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
18840 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  rs .** are not c
18850 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53  ounted..** .** S
18860 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
18870 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
18880 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
18890 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
188a0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
188b0 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
188c0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
188d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
188e0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
188f0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
18900 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
18910 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
18920 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
18930 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
18940 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
18950 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
18960 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
18970 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
18980 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
18990 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
189a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
189b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
189c0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
189d0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
189e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
189f0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
18a00 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
18a10 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
18a20 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
18a30 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
18a40 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
18a50 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
18a60 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
18a70 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
18a80 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
18a90 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
18aa0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
18ab0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
18ac0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
18ad0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
18ae0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
18af0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
18b00 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
18b10 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
18b20 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18b30 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
18b40 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
18b50 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
18b60 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
18b70 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
18b80 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18b90 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
18ba0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
18bb0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18bc0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
18bd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
18be0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
18bf0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
18c00 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
18c10 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
18c20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
18c30 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
18c40 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
18c50 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
18c60 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
18c70 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
18c80 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
18c90 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
18ca0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
18cb0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
18cc0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
18cd0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
18ce0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
18cf0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
18d00 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
18d10 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
18d20 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
18d30 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
18d40 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
18d50 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
18d60 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
18d70 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
18d80 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
18d90 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
18da0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
18db0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
18dc0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
18dd0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
18de0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18df0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
18e00 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
18e10 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
18e20 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
18e30 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
18e40 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
18e50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
18e60 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
18e70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18e80 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18e90 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
18ea0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18eb0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
18ec0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
18ed0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
18ee0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
18ef0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
18f00 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
18f10 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
18f20 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
18f30 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
18f40 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
18f50 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
18f60 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
18f70 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
18f80 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
18f90 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
18fa0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
18fb0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18fc0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
18fd0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
18fe0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
18ff0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
19000 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
19010 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
19020 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
19030 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
19040 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
19050 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
19060 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
19070 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19080 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
19090 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
190a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
190b0 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
190c0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
190d0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
190e0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
190f0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
19100 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
19110 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19120 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
19130 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
19140 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
19150 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
19160 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
19170 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
19180 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
19190 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
191a0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
191b0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
191c0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
191d0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
191e0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
191f0 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
19200 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
19210 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
19220 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
19230 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
19240 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
19250 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19260 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
19270 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
19280 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
19290 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
192a0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
192b0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
192c0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
192d0 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
192e0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
192f0 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
19300 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
19310 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
19320 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
19330 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
19340 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
19350 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
19360 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
19370 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
19380 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
19390 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
193a0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
193b0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
193c0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
193d0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
193e0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
193f0 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
19400 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
19410 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
19420 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
19430 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
19440 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
19450 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
19460 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
19470 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19480 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
19490 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
194a0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
194b0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
194c0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
194d0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
194e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
194f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
19500 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
19510 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
19520 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
19530 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
19540 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
19550 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
19560 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
19570 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
19580 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19590 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
195a0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
195b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
195c0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
195d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
195e0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
195f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
19600 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
19610 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
19620 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
19630 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
19640 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19650 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
19660 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
19670 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
19680 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
19690 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
196a0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
196b0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
196c0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
196d0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
196e0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
196f0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
19700 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
19710 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
19720 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19730 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
19740 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19750 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
19760 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
19770 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
19780 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
19790 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
197a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
197b0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
197c0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
197d0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
197e0 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
197f0 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
19800 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
19810 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
19820 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
19830 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
19840 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19850 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
19860 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19870 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65  r(D,X,P) routine
19880 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
19890 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74   function X.** t
198a0 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
198b0 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
198c0 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
198d0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
198e0 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20  ade to access a 
198f0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
19900 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
19910 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
19920 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61  ection] D when a
19930 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
19940 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
19950 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64  the table locked
19960 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
19970 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20  _busy_handler() 
19980 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
19990 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a  d to implement.*
199a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
199b0 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b  timeout()] and [
199c0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
199d0 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  out]..**.** ^If 
199e0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
199f0 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
19a00 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
19a10 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
19a20 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
19a30 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
19a40 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
19a50 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
19a60 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
19a70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
19a80 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
19a90 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
19aa0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
19ab0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
19ac0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19ad0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
19ae0 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
19af0 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
19b00 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
19b10 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
19b20 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
19b30 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
19b40 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
19b50 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
19b60 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
19b70 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
19b80 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
19b90 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
19ba0 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20   previously for 
19bb0 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
19bc0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
19bd0 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
19be0 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
19bf0 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
19c00 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
19c10 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
19c20 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
19c30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
19c40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
19c50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
19c60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
19c70 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
19c80 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
19c90 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
19ca0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
19cb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
19cc0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
19cd0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
19ce0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
19cf0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
19d00 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
19d10 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
19d20 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
19d30 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
19d40 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
19d50 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
19d60 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
19d70 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
19d80 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
19d90 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
19da0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
19db0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
19dc0 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
19dd0 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
19de0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
19df0 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
19e00 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
19e10 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
19e20 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
19e30 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
19e40 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
19e50 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
19e60 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
19e70 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
19e80 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19e90 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
19ea0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
19eb0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
19ec0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
19ed0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
19ee0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
19ef0 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
19f00 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
19f10 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
19f20 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
19f30 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
19f40 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
19f50 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
19f60 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
19f70 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
19f80 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
19f90 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
19fa0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
19fb0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
19fc0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
19fd0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
19fe0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
19ff0 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
1a000 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
1a010 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
1a020 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
1a030 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
1a040 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
1a050 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
1a060 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
1a070 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
1a080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1a090 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
1a0a0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
1a0b0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1a0c0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1a0d0 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
1a0e0 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
1a0f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a100 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
1a110 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
1a120 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
1a130 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
1a140 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
1a150 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
1a160 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1a170 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
1a180 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
1a190 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
1a1a0 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
1a1b0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
1a1c0 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
1a1d0 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
1a1e0 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
1a1f0 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
1a200 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
1a210 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
1a220 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
1a230 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1a240 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1a250 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1a260 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
1a270 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
1a280 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1a290 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
1a2a0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
1a2b0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
1a2c0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1a2d0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
1a2e0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
1a2f0 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
1a300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a310 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
1a320 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1a330 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1a340 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
1a350 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1a360 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1a370 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
1a380 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
1a390 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1a3a0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1a3b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1a3c0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1a3d0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1a3e0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a3f0 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1a400 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1a410 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1a420 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1a430 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1a440 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1a450 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1a460 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1a470 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1a480 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1a490 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1a4a0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1a4b0 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1a4c0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1a4d0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1a4e0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1a4f0 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1a500 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1a510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1a520 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1a530 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
1a540 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
1a550 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
1a560 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
1a570 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
1a580 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
1a590 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
1a5a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
1a5b0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1a5c0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1a5d0 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
1a5e0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1a5f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
1a600 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
1a610 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
1a620 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
1a630 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1a640 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1a650 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1a660 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1a670 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1a680 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1a690 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1a6a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
1a6b0 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
1a6c0 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
1a6d0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
1a6e0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
1a6f0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
1a700 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
1a710 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
1a720 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
1a730 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ies.** METHOD: s
1a740 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69  qlite3.**.** Thi
1a750 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1a760 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1a770 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1a780 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1a790 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1a7a0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1a7b0 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1a7c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1a7d0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1a7e0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1a7f0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1a800 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1a810 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1a820 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1a830 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1a840 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1a850 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1a860 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1a870 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1a880 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1a890 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1a8a0 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1a8b0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1a8c0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1a8d0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1a8e0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1a8f0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1a900 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1a910 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1a920 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1a930 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1a940 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1a950 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1a960 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1a970 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1a980 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1a990 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1a9a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a9b0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1a9c0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1a9d0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1a9e0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1a9f0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1aa00 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1aa10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1aa20 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1aa30 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1aa40 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1aa50 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1aa60 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1aa70 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1aa80 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1aa90 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1aaa0 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1aab0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1aac0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1aad0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1aae0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1aaf0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1ab00 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1ab10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1ab20 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1ab30 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1ab40 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1ab50 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1ab60 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1ab70 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1ab80 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1ab90 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1aba0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1abb0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1abc0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1abd0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1abe0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1abf0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1ac00 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1ac10 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1ac20 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1ac30 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1ac40 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1ac50 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1ac60 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1ac70 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1ac80 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1ac90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1aca0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1acb0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1acc0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1acd0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1ace0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1acf0 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1ad00 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1ad10 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1ad20 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1ad30 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1ad40 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1ad50 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1ad60 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1ad70 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1ad80 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1ad90 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1ada0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1adb0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1adc0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1add0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1ade0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1adf0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ae00 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1ae10 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1ae20 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1ae30 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1ae40 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1ae50 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1ae60 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1ae70 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1ae80 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ae90 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1aea0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1aeb0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1aec0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1aed0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1aee0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1aef0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1af00 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1af10 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1af20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1af30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1af40 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1af50 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1af60 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1af70 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1af80 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1af90 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1afa0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1afb0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1afc0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1afd0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1afe0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1aff0 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1b000 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1b010 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1b020 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1b030 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1b040 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1b050 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1b060 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1b070 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1b080 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1b090 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1b0a0 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1b0b0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1b0c0 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1b0d0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1b0e0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1b0f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1b100 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1b110 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b120 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1b130 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1b140 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1b150 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1b160 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1b170 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1b180 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1b190 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1b1a0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1b1b0 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1b1c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1b1d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1b1e0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1b1f0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1b200 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1b210 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1b220 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1b230 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1b240 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1b250 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1b260 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1b270 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1b280 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1b290 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1b2a0 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1b2b0 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1b2c0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1b2d0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1b2e0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1b2f0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1b300 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1b310 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1b320 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1b330 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1b340 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1b350 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1b360 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1b370 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1b380 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
1b390 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
1b3a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1b3b0 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
1b3c0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
1b3d0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
1b3e0 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
1b3f0 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
1b400 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
1b410 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
1b420 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
1b430 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
1b440 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1b450 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
1b460 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
1b470 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
1b480 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1b490 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
1b4a0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1b4b0 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
1b4c0 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
1b4d0 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
1b4e0 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
1b4f0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1b500 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
1b510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b520 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
1b530 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
1b540 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1b550 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
1b560 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
1b570 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
1b580 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
1b590 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
1b5a0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
1b5b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b5c0 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73  s understand mos
1b5d0 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20  t of the common 
1b5e0 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  K&R formatting o
1b5f0 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20  ptions,.** plus 
1b600 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1b610 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72  non-standard for
1b620 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62  mats, detailed b
1b630 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  elow..** Note th
1b640 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d  at some of the m
1b650 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d  ore obscure form
1b660 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66  atting options f
1b670 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d  rom recent.** C-
1b680 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64  library standard
1b690 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72  s are omitted fr
1b6a0 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e  om this implemen
1b6b0 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  tation..**.** ^T
1b6c0 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1b6d0 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1b6e0 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1b6f0 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1b700 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1b710 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1b720 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1b730 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1b740 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1b750 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1b760 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1b770 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1b780 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b790 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1b7a0 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1b7b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1b7c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b7d0 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1b7e0 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1b7f0 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1b800 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1b810 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1b820 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1b830 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1b840 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1b850 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1b860 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1b870 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1b880 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1b890 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1b8a0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1b8b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b8c0 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1b8d0 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1b8e0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1b8f0 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1b900 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1b910 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1b920 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1b930 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1b940 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1b950 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1b960 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1b970 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1b980 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1b990 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1b9a0 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1b9b0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1b9c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1b9d0 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1b9e0 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1b9f0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1ba00 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1ba10 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1ba20 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1ba30 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1ba40 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1ba50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1ba60 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1ba70 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1ba80 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1ba90 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1baa0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1bab0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1bac0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1bad0 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1bae0 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1baf0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1bb00 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1bb10 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1bb20 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1bb30 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1bb40 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1bb50 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1bb60 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1bb70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1bb80 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1bb90 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1bba0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1bbb0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1bbc0 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1bbd0 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1bbe0 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1bbf0 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1bc00 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1bc10 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1bc20 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1bc30 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1bc40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1bc50 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1bc60 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1bc70 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1bc80 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1bc90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1bca0 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1bcb0 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1bcc0 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1bcd0 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1bce0 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1bcf0 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1bd00 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1bd10 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1bd20 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1bd30 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1bd40 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1bd50 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1bd60 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e  ", "%Q", "%w" an
1bd70 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1bd80 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1bd90 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1bda0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1bdb0 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1bdc0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1bdd0 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1bde0 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1bdf0 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1be00 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1be10 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1be20 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1be30 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1be40 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1be50 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1be60 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1be70 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1be80 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1be90 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1bea0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1beb0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1bec0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1bed0 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1bee0 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1bef0 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1bf00 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1bf10 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1bf20 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1bf30 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1bf40 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1bf50 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1bf60 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1bf70 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1bf80 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1bf90 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1bfa0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1bfb0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1bfc0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1bfd0 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1bfe0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1bff0 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1c000 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1c010 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1c020 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1c030 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1c040 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c050 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1c060 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1c070 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1c080 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1c090 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1c0a0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1c0b0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1c0c0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1c0d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c0e0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1c0f0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1c100 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1c110 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1c120 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1c130 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1c140 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1c150 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1c160 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1c170 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1c180 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1c190 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1c1a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c1b0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1c1c0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1c1d0 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1c1e0 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1c1f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c200 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1c210 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1c220 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1c230 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1c240 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1c250 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1c260 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1c270 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1c280 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1c290 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1c2a0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1c2b0 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1c2c0 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1c2d0 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1c2e0 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1c2f0 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1c300 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1c310 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1c320 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1c330 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1c340 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1c350 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1c360 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1c370 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1c380 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1c390 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1c3a0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1c3b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c3c0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1c3d0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1c3e0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1c3f0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1c400 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1c410 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1c420 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1c430 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1c440 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1c450 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c460 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1c470 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1c480 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1c490 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1c4a0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1c4b0 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1c4c0 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1c4d0 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1c4e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1c4f0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
1c500 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20   option is like 
1c510 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74  "%q" except that
1c520 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a   it expects to.*
1c530 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77  * be contained w
1c540 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f  ithin double-quo
1c550 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73  tes instead of s
1c560 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e  ingle quotes, an
1c570 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20  d it.** escapes 
1c580 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65  the double-quote
1c590 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65   character inste
1c5a0 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65  ad of the single
1c5b0 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63  -quote.** charac
1c5c0 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22  ter.)^  The "%w"
1c5d0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1c5e0 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  on is intended f
1c5f0 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74  or safely insert
1c600 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64  ing.** table and
1c610 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e   column names in
1c620 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64  to a constructed
1c630 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1c640 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1c650 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1c660 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1c670 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1c680 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1c690 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1c6a0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1c6b0 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1c6c0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1c6d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1c6e0 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1c6f0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1c700 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
1c710 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1c720 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
1c730 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1c740 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1c750 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
1c760 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1c770 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1c780 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
1c790 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
1c7a0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1c7b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1c7c0 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1c7d0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1c7e0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1c7f0 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1c800 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1c810 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1c820 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1c830 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1c840 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1c850 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1c860 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1c870 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1c880 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1c890 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1c8a0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1c8b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1c8c0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1c8d0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1c8e0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1c8f0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1c900 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1c910 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1c920 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1c930 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1c940 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1c950 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1c960 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1c970 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1c980 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1c990 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1c9a0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1c9b0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1c9c0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1c9d0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1c9e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1c9f0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1ca00 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1ca10 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1ca20 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1ca30 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1ca40 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1ca50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1ca60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ca70 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
1ca80 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
1ca90 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
1caa0 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
1cab0 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
1cac0 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
1cad0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1cae0 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
1caf0 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
1cb00 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1cb10 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1cb20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1cb30 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1cb40 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1cb50 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1cb60 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1cb70 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1cb80 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1cb90 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1cba0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1cbb0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1cbc0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1cbd0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1cbe0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1cbf0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1cc00 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1cc10 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1cc20 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1cc30 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1cc40 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1cc50 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1cc60 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1cc70 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1cc80 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1cc90 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1cca0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1ccb0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1ccc0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1ccd0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1cce0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1ccf0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1cd00 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1cd10 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1cd20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1cd30 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1cd40 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1cd50 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1cd60 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1cd70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1cd80 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1cd90 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
1cda0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1cdb0 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
1cdc0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1cdd0 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1cde0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1cdf0 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
1ce00 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
1ce10 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
1ce20 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1ce30 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
1ce40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1ce50 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1ce60 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1ce70 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1ce80 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
1ce90 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
1cea0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1ceb0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
1cec0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1ced0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1cee0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1cef0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1cf00 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1cf10 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
1cf20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1cf30 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
1cf40 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1cf50 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1cf60 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1cf70 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1cf80 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
1cf90 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
1cfa0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1cfb0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1cfc0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1cfd0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1cfe0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1cff0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1d000 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1d010 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1d020 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1d030 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1d040 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d050 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1d060 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1d070 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1d080 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1d090 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
1d0a0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
1d0b0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
1d0c0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1d0d0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1d0e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1d0f0 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
1d100 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
1d110 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
1d120 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1d130 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1d140 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
1d150 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
1d160 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
1d170 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1d180 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
1d190 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
1d1a0 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
1d1b0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1d1c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d1d0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1d1e0 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
1d1f0 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
1d200 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1d210 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
1d220 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1d230 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
1d240 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
1d250 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
1d260 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
1d270 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1d280 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
1d290 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
1d2a0 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
1d2b0 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
1d2c0 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
1d2d0 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
1d2e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1d2f0 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
1d300 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1d310 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
1d320 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
1d330 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
1d340 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
1d350 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
1d360 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
1d370 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
1d380 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
1d390 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1d3a0 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
1d3b0 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
1d3c0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
1d3d0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1d3e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1d3f0 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
1d400 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
1d410 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1d420 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1d430 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1d440 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
1d450 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
1d460 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1d470 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
1d480 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1d490 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1d4a0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1d4b0 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1d4c0 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1d4d0 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1d4e0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1d4f0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1d500 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1d510 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1d520 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1d530 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1d540 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1d550 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1d560 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1d570 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1d580 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1d590 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1d5a0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1d5b0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1d5c0 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1d5d0 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1d5e0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1d5f0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1d600 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1d610 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1d620 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1d630 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1d640 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1d650 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1d660 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1d670 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1d680 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1d690 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1d6a0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1d6b0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1d6c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1d6d0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1d6e0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1d6f0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1d700 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1d710 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1d720 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1d730 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1d740 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1d750 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1d760 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1d770 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1d780 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1d790 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1d7a0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1d7b0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1d7c0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1d7d0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1d7e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1d7f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1d800 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1d810 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1d820 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1d830 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1d840 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1d850 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1d860 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1d870 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1d880 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1d890 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1d8a0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1d8b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1d8c0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1d8d0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1d8e0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1d8f0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1d900 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1d910 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1d920 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1d930 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1d940 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1d950 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1d960 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1d970 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e  oc64(sqlite3_uin
1d980 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  t64);.void *sqli
1d990 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1d9a0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  *, int);.void *s
1d9b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1d9c0 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f  (void*, sqlite3_
1d9d0 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  uint64);.void sq
1d9e0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1d9f0 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  );.sqlite3_uint6
1da00 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
1da10 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1da20 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1da30 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
1da40 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
1da50 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
1da60 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
1da70 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
1da80 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
1da90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
1daa0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
1dab0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
1dac0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1dad0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
1dae0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
1daf0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1db00 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
1db10 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
1db20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1db30 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
1db40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1db50 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1db60 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
1db70 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
1db80 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
1db90 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
1dba0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1dbb0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
1dbc0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1dbd0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
1dbe0 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
1dbf0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
1dc00 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
1dc10 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
1dc20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
1dc30 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1dc40 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
1dc50 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
1dc60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1dc70 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1dc80 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
1dc90 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
1dca0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
1dcb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1dcc0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1dcd0 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
1dce0 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
1dcf0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
1dd00 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
1dd10 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
1dd20 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
1dd30 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
1dd40 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1dd50 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
1dd60 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
1dd70 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
1dd80 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
1dd90 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1dda0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1ddb0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
1ddc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1ddd0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1dde0 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
1ddf0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1de00 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
1de10 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
1de20 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
1de30 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
1de40 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
1de50 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
1de60 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1de70 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
1de80 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1de90 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1dea0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1deb0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1dec0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1ded0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1dee0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1def0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1df00 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1df10 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1df20 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1df30 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1df40 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1df50 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1df60 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1df70 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1df80 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1df90 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1dfa0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1dfb0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1dfc0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1dfd0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1dfe0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1dff0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1e000 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1e010 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1e020 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1e030 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1e040 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1e050 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1e060 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1e070 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1e080 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1e090 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1e0a0 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70  r P..** ^The P p
1e0b0 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20  arameter can be 
1e0c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1e0d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
1e0e0 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
1e0f0 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
1e100 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
1e110 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
1e120 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
1e130 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70   one or a NULL p
1e140 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68  ointer for P, th
1e150 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a  en the PRNG is.*
1e160 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  * seeded using r
1e170 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
1e180 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ed from the xRan
1e190 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1e1a0 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74  f.** the default
1e1b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1e1c0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
1e1d0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
1e1e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1e1f0 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
1e200 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e   more and a.** n
1e210 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74  on-NULL P then t
1e220 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
1e230 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
1e240 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
1e250 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
1e260 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
1e270 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
1e280 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
1e290 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1e2a0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1e2b0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1e2c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1e2d0 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1e2e0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1e2f0 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
1e300 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1e310 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1e320 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1e330 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1e340 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1e350 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e360 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1e370 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1e380 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1e390 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e3a0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1e3b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1e3c0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1e3d0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1e3e0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1e3f0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1e400 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e410 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1e420 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1e430 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1e440 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1e450 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1e460 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1e470 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1e480 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1e490 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1e4a0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1e4b0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1e4c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e4d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1e4e0 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1e4f0 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1e500 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1e510 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e520 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1e530 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1e540 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1e550 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1e560 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1e570 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1e580 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1e590 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1e5a0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1e5b0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1e5c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1e5d0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1e5e0 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1e5f0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1e600 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1e610 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1e620 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e630 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1e640 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1e650 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1e660 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1e670 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1e680 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1e690 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e6a0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1e6b0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1e6c0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1e6d0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1e6e0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1e6f0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1e700 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1e710 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1e720 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1e730 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1e740 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1e750 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1e760 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1e770 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1e780 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1e790 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1e7a0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1e7b0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1e7c0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1e7d0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1e7e0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1e7f0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1e800 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1e810 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1e820 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1e830 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1e840 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1e850 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1e860 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1e870 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1e880 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1e890 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1e8a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1e8b0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1e8c0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1e8d0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1e8e0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1e8f0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1e900 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1e910 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1e920 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1e930 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1e940 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1e950 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1e960 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1e970 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1e980 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1e990 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1e9a0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1e9b0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1e9c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1e9d0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1e9e0 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1e9f0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1ea00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1ea10 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1ea20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1ea30 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1ea40 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1ea50 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1ea60 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1ea70 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1ea80 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1ea90 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1eaa0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1eab0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1eac0 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1ead0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1eae0 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1eaf0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1eb00 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1eb10 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1eb20 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1eb30 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1eb40 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1eb50 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1eb60 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1eb70 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1eb80 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1eb90 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1eba0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1ebb0 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1ebc0 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1ebd0 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1ebe0 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1ebf0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1ec00 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1ec10 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1ec20 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1ec30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1ec40 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1ec50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1ec60 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1ec70 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1ec80 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1ec90 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1eca0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1ecb0 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1ecc0 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1ecd0 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1ece0 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1ecf0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1ed00 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1ed10 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1ed20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1ed30 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1ed40 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1ed50 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1ed60 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1ed70 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1ed80 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1ed90 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1eda0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1edb0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1edc0 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1edd0 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1ede0 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1edf0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1ee00 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1ee10 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1ee20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1ee30 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1ee40 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1ee50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1ee60 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1ee70 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1ee80 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1ee90 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1eea0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1eeb0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1eec0 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1eed0 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1eee0 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1eef0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1ef00 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1ef10 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1ef20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1ef30 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1ef40 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1ef50 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1ef60 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1ef70 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1ef80 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1ef90 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1efa0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1efb0 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1efc0 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1efd0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1efe0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1eff0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1f000 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1f010 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1f020 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1f030 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1f040 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1f050 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1f060 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1f070 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1f080 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1f090 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1f0a0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1f0b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1f0c0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1f0d0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1f0e0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1f0f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1f100 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1f110 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1f120 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1f130 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f140 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1f150 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1f160 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1f170 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1f180 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1f190 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1f1a0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1f1b0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1f1c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1f1d0 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1f1e0 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1f1f0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1f200 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1f210 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1f220 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1f230 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1f240 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1f250 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1f260 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1f270 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1f280 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1f290 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f2a0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1f2b0 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1f2c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1f2d0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1f2e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1f2f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1f300 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1f310 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1f320 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1f330 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1f340 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1f350 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1f360 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1f370 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1f380 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1f390 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1f3a0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1f3b0 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1f3c0 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1f3d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1f3e0 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1f3f0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1f400 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1f410 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
1f420 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1f430 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1f440 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1f450 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1f460 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1f470 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1f480 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1f490 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1f4a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1f4b0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1f4c0 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1f4d0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1f4e0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1f4f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f500 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1f510 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1f520 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1f530 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1f540 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1f550 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1f560 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1f570 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1f580 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1f590 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1f5a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1f5b0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1f5c0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1f5d0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1f5e0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1f5f0 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1f600 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1f610 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1f620 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
1f630 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
1f640 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
1f650 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1f660 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1f670 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1f680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1f690 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1f6a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1f6b0 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1f6c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f6d0 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1f6e0 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1f6f0 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1f700 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1f710 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1f720 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1f730 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1f740 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1f750 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1f760 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1f770 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1f780 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1f790 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1f7a0 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1f7b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1f7c0 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1f7d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1f7e0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1f7f0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1f800 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1f810 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1f820 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1f830 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1f840 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1f850 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1f860 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1f870 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1f880 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1f890 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1f8a0 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1f8b0 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1f8c0 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1f8d0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1f8e0 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1f8f0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1f900 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1f910 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1f920 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1f930 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1f940 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1f950 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1f960 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1f970 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1f980 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1f990 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1f9a0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1f9b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1f9c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1f9d0 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1f9e0 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1f9f0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1fa00 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1fa10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1fa20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1fa30 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1fa40 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1fa50 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1fa60 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1fa70 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1fa80 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1fa90 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1faa0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1fab0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1fac0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1fad0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1fae0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1faf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fb00 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1fb10 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1fb20 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1fb30 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1fb40 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1fb50 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1fb60 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1fb70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fb80 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1fb90 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1fba0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1fbb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fbc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fbd0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1fbe0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1fbf0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1fc00 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1fc10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fc20 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1fc30 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1fc40 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1fc50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1fc60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fc70 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1fc80 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1fc90 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1fca0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fcb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fcc0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1fcd0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1fce0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1fcf0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fd00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fd10 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1fd20 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1fd30 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1fd40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1fd50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fd60 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1fd70 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1fd80 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1fd90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1fda0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fdb0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1fdc0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1fdd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1fde0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fdf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1fe00 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1fe10 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1fe20 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1fe30 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fe40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1fe50 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1fe60 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1fe70 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1fe80 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fe90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1fea0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1feb0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1fec0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1fed0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fee0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1fef0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1ff00 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1ff10 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ff20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ff30 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ff40 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1ff50 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1ff60 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1ff70 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ff80 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1ff90 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1ffa0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1ffb0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ffc0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ffd0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1ffe0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1fff0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
20000 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20010 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20020 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
20030 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
20040 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
20050 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20060 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20070 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
20080 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
20090 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
200a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
200b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
200c0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
200d0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
200e0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
200f0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
20100 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
20110 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
20120 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
20130 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20140 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
20150 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20160 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
20170 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
20180 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20190 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
201a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
201b0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
201c0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
201d0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
201e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
201f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20200 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
20210 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
20220 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
20230 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
20240 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20250 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
20260 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
20270 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
20280 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
202a0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
202b0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
202c0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
202d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
202e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
202f0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
20300 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
20310 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
20320 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
20340 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
20350 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
20360 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20370 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
20390 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
203a0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
203b0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
203c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
203d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
203e0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
203f0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
20400 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
20410 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
20420 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20430 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
20440 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
20450 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
20460 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
20470 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
20480 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
20490 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
204a0 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
204b0 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
204c0 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
204d0 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
204e0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
204f0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
20500 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
20510 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
20520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
20530 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
20540 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
20550 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
20560 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
20570 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
20580 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20590 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
205a0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
205b0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
205c0 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
205d0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
205e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 63  These routines c
205f0 6f 6e 74 72 6f 6c 20 63 61 6c 6c 62 61 63 6b 20  ontrol callback 
20600 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
20610 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
20620 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
20630 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
20640 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
20650 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
20660 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
20670 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
20680 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
20690 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
206a0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
206b0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
206c0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
206d0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
206e0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
206f0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
20700 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
20710 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
20720 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
20730 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
20740 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
20750 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
20760 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
20770 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
20780 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
20790 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
207a0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
207b0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
207c0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
207d0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
207e0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
207f0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
20800 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
20810 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
20820 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
20830 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
20840 74 65 33 5f 67 65 74 5f 74 72 61 63 65 28 44 2c  te3_get_trace(D,
20850 58 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  X,P)] interface 
20860 77 72 69 74 65 73 20 69 6e 74 6f 20 58 20 61 6e  writes into X an
20870 64 20 50 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  d P the.** value
20880 73 20 6f 66 20 74 68 65 20 74 72 61 63 65 20 63  s of the trace c
20890 61 6c 6c 62 61 63 6b 20 61 6e 64 20 70 6f 69 6e  allback and poin
208a0 74 65 72 20 73 65 74 20 62 79 20 74 68 65 20 6d  ter set by the m
208b0 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 5b 73  ost recent.** [s
208c0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
208d0 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65  call on the same
208e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
208f0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
20900 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
20910 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
20920 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
20930 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20940 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
20950 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
20960 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
20970 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
20980 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
20990 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
209a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
209b0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
209c0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
209d0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
209e0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
209f0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
20a00 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
20a10 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
20a20 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
20a30 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20a40 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
20a50 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
20a60 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
20a70 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
20a80 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
20a90 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
20aa0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
20ab0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
20ac0 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
20ad0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
20ae0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
20af0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
20b00 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
20b10 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
20b20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
20b30 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
20b40 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
20b50 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
20b60 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20b70 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
20b80 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
20b90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
20ba0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
20bb0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
20bc0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 70 72   [sqlite3_get_pr
20bd0 6f 66 69 6c 65 28 44 2c 58 2c 50 29 5d 20 69 6e  ofile(D,X,P)] in
20be0 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 69  terface writes i
20bf0 6e 74 6f 20 58 20 61 6e 64 20 50 20 74 68 65 0a  nto X and P the.
20c00 2a 2a 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  ** values of the
20c10 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
20c20 6b 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 73 65  k and pointer se
20c30 74 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  t by the most re
20c40 63 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  cent.** [sqlite3
20c50 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c  _profile()] call
20c60 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
20c70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20c80 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20  n] D..**.** All 
20c90 6f 66 20 74 68 65 20 74 72 61 63 69 6e 67 20 61  of the tracing a
20ca0 6e 64 20 70 72 6f 66 69 6c 65 20 69 6e 74 65 72  nd profile inter
20cb0 66 61 63 65 73 20 61 72 65 20 6f 6d 69 74 74 65  faces are omitte
20cc0 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53  d when the.** [S
20cd0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45  QLITE_OMIT_TRACE
20ce0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
20cf0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
20d00 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
20d10 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
20d20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
20d30 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
20d40 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
20d50 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
20d60 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
20d70 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
20d80 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
20d90 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
20da0 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  void*);.void sql
20db0 69 74 65 33 5f 67 65 74 5f 74 72 61 63 65 28 63  ite3_get_trace(c
20dc0 6f 6e 73 74 20 73 71 6c 69 74 65 33 2a 2c 20 76  onst sqlite3*, v
20dd0 6f 69 64 28 2a 2a 29 28 76 6f 69 64 2a 2c 63 6f  oid(**)(void*,co
20de0 6e 73 74 20 63 68 61 72 2a 29 2c 76 6f 69 64 2a  nst char*),void*
20df0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
20e00 5f 67 65 74 5f 70 72 6f 66 69 6c 65 28 63 6f 6e  _get_profile(con
20e10 73 74 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  st sqlite3*,.   
20e20 76 6f 69 64 28 2a 2a 29 28 76 6f 69 64 2a 2c 63  void(**)(void*,c
20e30 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
20e40 65 33 5f 75 69 6e 74 36 34 29 2c 76 6f 69 64 2a  e3_uint64),void*
20e50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20e60 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
20e70 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
20e80 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
20e90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
20ea0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
20eb0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
20ec0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
20ed0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
20ee0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
20ef0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
20f00 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
20f10 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
20f20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
20f30 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
20f40 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
20f50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
20f60 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
20f70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
20f80 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
20f90 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
20fa0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
20fb0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
20fc0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
20fd0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
20fe0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
20ff0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
21000 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
21010 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
21020 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21030 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
21040 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
21050 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
21060 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
21070 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
21080 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
21090 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
210a0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
210b0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
210c0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
210d0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
210e0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
210f0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
21100 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
21110 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
21120 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
21130 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
21140 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
21150 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
21160 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
21170 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
21180 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
21190 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
211a0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
211b0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
211c0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
211d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
211e0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
211f0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
21200 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
21210 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
21220 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
21230 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
21240 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
21250 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
21260 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
21270 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
21280 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
21290 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
212a0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
212b0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
212c0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
212d0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
212e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
212f0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
21300 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
21310 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
21320 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
21330 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21340 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
21350 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
21360 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
21370 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
21380 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
21390 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
213a0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
213b0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
213c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
213d0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
213e0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
213f0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
21400 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
21410 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
21420 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
21430 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
21440 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
21450 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
21460 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
21470 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53  nnection.** CONS
21480 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
21490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
214a0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
214b0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
214c0 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
214d0 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
214e0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
214f0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
21500 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
21510 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
21520 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
21530 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
21540 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
21550 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
21560 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
21570 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
21580 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
21590 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
215a0 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
215b0 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
215c0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
215d0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
215e0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
215f0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
21600 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
21610 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
21620 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
21630 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
21640 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
21650 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
21660 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
21670 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
21680 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
21690 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
216a0 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
216b0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
216c0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
216d0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
216e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
216f0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
21700 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
21710 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
21720 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
21730 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
21740 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
21750 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
21760 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
21770 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
21780 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
21790 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
217a0 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
217b0 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
217c0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
217d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
217e0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
217f0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
21800 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  ng will be UTF-8
21810 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63   for databases c
21820 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
21830 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
21840 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
21850 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75  2().  ^The defau
21860 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
21870 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65  databases.** cre
21880 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74  ated using sqlit
21890 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c  e3_open16() will
218a0 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68   be UTF-16 in th
218b0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
218c0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  der..**.** Wheth
218d0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
218e0 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
218f0 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
21900 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
21910 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
21920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21930 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
21940 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
21950 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
21960 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
21970 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
21980 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
21990 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
219a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
219b0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
219c0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
219d0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
219e0 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
219f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
21a00 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
21a10 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
21a20 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
21a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21a40 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
21a50 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
21a60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21a70 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
21a80 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
21a90 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
21aa0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
21ab0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
21ac0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
21ad0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
21ae0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
21af0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
21b00 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
21b10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
21b20 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
21b30 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
21b40 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
21b50 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
21b60 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
21b70 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
21b80 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
21b90 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
21ba0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
21bb0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
21bc0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
21bd0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
21be0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
21bf0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
21c00 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
21c10 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
21c20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21c30 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21c40 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
21c50 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
21c60 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
21c70 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
21c80 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
21c90 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
21ca0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
21cb0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
21cc0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
21cd0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
21ce0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
21cf0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
21d00 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
21d10 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
21d20 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
21d30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
21d40 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
21d50 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
21d60 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
21d70 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
21d80 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
21d90 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
21da0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
21db0 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
21dc0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
21dd0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
21de0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21df0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
21e00 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
21e10 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
21e20 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
21e30 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21e40 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
21e50 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
21e60 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
21e70 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
21e80 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
21e90 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
21ea0 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
21eb0 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
21ec0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
21ed0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
21ee0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
21ef0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21f00 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
21f10 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
21f20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21f30 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
21f40 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
21f50 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
21f60 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
21f70 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
21f80 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
21f90 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
21fa0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
21fb0 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
21fc0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
21fd0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
21fe0 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
21ff0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
22000 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
22010 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
22020 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
22030 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
22040 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
22050 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
22060 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
22070 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
22080 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
22090 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
220a0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
220b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
220c0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
220d0 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
220e0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
220f0 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
22100 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
22110 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
22120 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
22130 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
22140 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
22150 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
22160 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
22170 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
22180 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22190 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
221a0 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
221b0 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
221c0 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
221d0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
221e0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
221f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
22200 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
22210 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
22220 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
22230 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
22240 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
22250 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
22260 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
22270 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
22280 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
22290 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
222a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
222b0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
222c0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
222d0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
222e0 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
222f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
22300 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
22310 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
22320 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
22330 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
22340 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
22350 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
22360 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
22370 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
22380 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
22390 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
223a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
223b0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
223c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
223d0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
223e0 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
223f0 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
22400 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
22410 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
22420 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
22430 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
22440 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
22450 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
22460 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
22470 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
22480 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
22490 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
224a0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
224b0 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
224c0 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
224d0 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
224e0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
224f0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
22500 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
22510 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
22520 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
22530 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
22540 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
22550 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
22560 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
22570 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
22580 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
22590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
225a0 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
225b0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
225c0 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
225d0 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
225e0 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
225f0 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
22600 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
22610 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
22620 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
22630 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
22640 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
22650 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
22660 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
22670 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
22680 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
22690 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
226a0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
226b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
226c0 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
226d0 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
226e0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
226f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
22700 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
22710 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
22720 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
22730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
22740 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
22750 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
22760 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
22770 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
22780 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
22790 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
227a0 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
227b0 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
227c0 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
227d0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
227e0 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
227f0 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
22800 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
22810 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
22820 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
22830 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
22840 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
22850 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
22860 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
22870 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
22880 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
22890 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
228a0 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
228b0 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
228c0 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
228d0 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
228e0 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
228f0 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
22900 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
22910 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
22920 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
22930 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
22940 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
22950 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
22960 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
22970 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
22980 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
22990 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
229a0 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
229b0 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
229c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
229d0 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
229e0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
229f0 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
22a00 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
22a10 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
22a20 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
22a30 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
22a40 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
22a50 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
22a60 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
22a70 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
22a80 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
22a90 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
22aa0 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
22ab0 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
22ac0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
22ad0 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
22ae0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
22af0 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
22b00 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
22b10 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
22b20 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e  e path. .** ^(On
22b30 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
22b40 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
22b50 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
22b60 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
22b70 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
22b80 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a  e.g. "C:").)^.**
22b90 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71  .** [[core URI q
22ba0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d  uery parameters]
22bb0 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63  ].** The query c
22bc0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
22bd0 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61  I may contain pa
22be0 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
22bf0 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a  e interpreted.**
22c00 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74   either by SQLit
22c10 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20  e itself, or by 
22c20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20  a [VFS | custom 
22c30 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
22c40 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61  on]..** SQLite a
22c50 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20  nd its built-in 
22c60 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65  [VFSes] interpre
22c70 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  t the.** followi
22c80 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ng query paramet
22c90 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
22ca0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
22cb0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
22cc0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
22cd0 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
22ce0 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
22cf0 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
22d00 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
22d10 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
22d20 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
22d30 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
22d40 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
22d50 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
22d60 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
22d70 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
22d80 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
22d90 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
22da0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
22db0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
22dc0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
22dd0 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
22de0 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
22df0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
22e00 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
22e10 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
22e20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
22e30 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
22e40 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
22e50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
22e60 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
22e70 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
22e80 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
22e90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
22ea0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22eb0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
22ec0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
22ed0 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
22ee0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
22ef0 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
22f00 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
22f10 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
22f20 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
22f30 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
22f40 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
22f50 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
22f60 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
22f70 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
22f80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
22f90 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
22fa0 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
22fb0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
22fc0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
22fd0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
22fe0 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
22ff0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
23000 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
23010 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23020 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
23030 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
23040 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
23050 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
23060 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
23070 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
23080 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
23090 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
230a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
230b0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
230c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
230d0 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
230e0 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
230f0 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
23100 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
23110 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
23120 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
23130 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
23140 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
23150 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
23160 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
23170 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
23180 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
23190 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
231a0 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
231b0 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
231c0 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
231d0 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
231e0 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
231f0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
23200 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
23210 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
23220 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
23230 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
23240 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
23250 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
23260 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
23270 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
23280 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
23290 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
232a0 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
232b0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
232c0 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
232d0 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
232e0 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
232f0 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
23300 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
23310 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
23320 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
23330 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
23340 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
23350 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
23360 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
23370 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
23380 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
23390 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
233a0 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
233b0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
233c0 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
233d0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
233e0 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
233f0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
23400 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
23410 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
23420 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
23430 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
23440 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
23450 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
23460 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
23470 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
23480 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
23490 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
234a0 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
234b0 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
234c0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
234d0 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
234e0 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69  psow parameter i
234f0 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72  ndicates whether
23500 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20   or not the.**  
23510 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76     [powersafe ov
23520 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74  erwrite] propert
23530 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e  y does or does n
23540 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a  ot apply to the.
23550 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d  **     storage m
23560 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68  edia on which th
23570 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
23580 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20  resides..**.**  
23590 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f  <li> <b>nolock</
235a0 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20  b>: ^The nolock 
235b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
235c0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72  oolean query par
235d0 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68  ameter.**     wh
235e0 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62  ich if set disab
235f0 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  les file locking
23600 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75   in rollback jou
23610 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69  rnal modes.  Thi
23620 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66  s.**     is usef
23630 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ul for accessing
23640 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61   a database on a
23650 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74   filesystem that
23660 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
23670 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67   support locking
23680 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74  .  Caution:  Dat
23690 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
236a0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
236b0 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d   two.**     or m
236c0 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72  ore processes wr
236d0 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ite to the same 
236e0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79  database and any
236f0 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a   one of those.**
23700 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75       processes u
23710 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a  ses nolock=1..**
23720 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d  .**  <li> <b>imm
23730 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65  utable</b>: ^The
23740 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d   immutable param
23750 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
23760 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  n query.**     p
23770 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e  arameter that in
23780 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
23790 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
237a0 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20  s stored on.**  
237b0 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64     read-only med
237c0 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74  ia.  ^When immut
237d0 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c  able is set, SQL
237e0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
237f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
23800 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74  base file cannot
23810 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65   be changed, eve
23820 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77  n by a process w
23830 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20  ith higher.**   
23840 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64    privilege, and
23850 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   so the database
23860 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d   is opened read-
23870 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63  only and all loc
23880 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20  king.**     and 
23890 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e  change detection
238a0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43   is disabled.  C
238b0 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20  aution: Setting 
238c0 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a  the immutable.**
238d0 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e       property on
238e0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
238f0 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61   that does in fa
23900 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65  ct change can re
23910 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69  sult.**     in i
23920 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72  ncorrect query r
23930 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53  esults and/or [S
23940 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
23950 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65  rrors..**     Se
23960 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
23970 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
23980 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c  ..**       .** <
23990 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
239a0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
239b0 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
239c0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
239d0 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
239e0 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
239f0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
23a00 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
23a10 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
23a20 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
23a30 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
23a40 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
23a50 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
23a60 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
23a70 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
23a80 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
23a90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
23aa0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
23ab0 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
23ac0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
23ad0 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
23ae0 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
23af0 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
23b00 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
23b10 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
23b20 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
23b30 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
23b40 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
23b50 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
23b60 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
23b70 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
23b80 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
23b90 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
23ba0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
23bb0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
23bc0 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
23bd0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
23be0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
23bf0 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
23c00 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
23c10 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
23c20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
23c30 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
23c40 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
23c50 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23c60 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
23c70 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
23c80 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
23c90 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
23ca0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
23cb0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
23cc0 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
23cd0 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
23ce0 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
23cf0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
23d00 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
23d10 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
23d20 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
23d30 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
23d40 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
23d50 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
23d60 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
23d70 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
23d80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
23d90 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
23da0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
23db0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
23dc0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
23dd0 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
23de0 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
23df0 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
23e00 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
23e10 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
23e20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
23e30 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
23e40 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
23e50 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
23e60 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23e70 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
23e80 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
23e90 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
23ea0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
23eb0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
23ec0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
23ed0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
23ee0 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
23ef0 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
23f00 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
23f10 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
23f20 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23f30 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
23f40 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64  ta.db?vfs=unix-d
23f50 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20  otfile <td>.**  
23f60 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
23f70 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
23f80 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
23f90 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
23fa0 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20  x-dotfile".**   
23fb0 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73         that uses
23fc0 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c   dot-files in pl
23fd0 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76  ace of posix adv
23fe0 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a  isory locking..*
23ff0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
24000 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
24010 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
24020 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
24030 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
24040 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
24050 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
24060 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
24070 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
24080 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
24090 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
240a0 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
240b0 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
240c0 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
240d0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
240e0 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
240f0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
24100 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
24110 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
24120 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
24130 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
24140 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
24150 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
24160 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
24170 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
24180 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
24190 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
241a0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
241b0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
241c0 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
241d0 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
241e0 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
241f0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
24200 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
24210 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
24220 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
24230 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
24240 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
24250 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
24260 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
24270 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
24280 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
24290 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
242a0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
242b0 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
242c0 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
242d0 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
242e0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
242f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24300 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
24310 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
24320 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
24330 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
24340 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
24350 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
24360 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
24370 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
24380 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
24390 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
243a0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
243b0 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
243c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
243d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
243e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
243f0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
24400 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
24410 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
24420 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
24430 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
24440 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
24450 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
24460 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
24470 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
24480 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
24490 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
244a0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
244b0 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
244c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
244d0 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
244e0 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
244f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
24500 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
24510 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
24520 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
24530 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
24540 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
24550 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
24560 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
24570 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
24580 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
24590 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
245a0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
245b0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
245c0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
245d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
245e0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
245f0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
24600 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
24610 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
24620 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
24630 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
24640 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
24650 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
24660 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
24670 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
24680 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
24690 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
246a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
246b0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
246c0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
246d0 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
246e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
246f0 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
24700 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
24710 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
24720 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
24730 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
24740 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
24750 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
24760 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
24770 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
24780 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
24790 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
247a0 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
247b0 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
247c0 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
247d0 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
247e0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
247f0 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
24800 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
24810 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
24820 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
24830 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
24840 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
24850 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
24860 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
24870 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
24880 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
24890 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
248a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
248b0 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
248c0 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
248d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
248e0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
248f0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
24900 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
24910 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
24920 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
24930 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
24940 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
24950 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
24960 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
24970 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
24980 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
24990 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
249a0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
249b0 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
249c0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
249d0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
249e0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
249f0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
24a00 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
24a10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24a20 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
24a30 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
24a40 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
24a50 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
24a60 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
24a70 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
24a80 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
24a90 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
24aa0 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
24ab0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24ac0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
24ad0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
24ae0 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
24af0 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
24b00 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
24b10 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
24b20 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
24b30 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
24b40 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
24b50 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
24b60 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
24b70 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24b80 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
24b90 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
24ba0 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
24bb0 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
24bc0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
24bd0 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
24be0 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
24bf0 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
24c00 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
24c10 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
24c20 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
24c30 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
24c40 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
24c50 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
24c60 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
24c70 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
24c80 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
24c90 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24ca0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
24cb0 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
24cc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
24cd0 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
24ce0 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
24cf0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
24d00 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
24d10 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
24d20 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
24d30 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
24d40 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
24d50 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
24d60 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
24d70 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
24d80 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
24d90 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
24da0 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
24db0 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
24dc0 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
24dd0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24de0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
24df0 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
24e00 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
24e10 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
24e20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
24e30 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
24e40 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
24e50 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
24e60 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
24e70 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
24e80 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
24e90 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
24ea0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
24eb0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
24ec0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
24ed0 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
24ee0 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
24ef0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
24f00 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
24f10 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
24f20 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
24f30 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
24f40 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
24f50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
24f60 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
24f70 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
24f80 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
24f90 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
24fa0 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
24fb0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
24fc0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
24fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24fe0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
24ff0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45  d Messages.** ME
25000 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
25010 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
25020 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f   recent sqlite3_
25030 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63  * API call assoc
25040 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b  iated with .** [
25050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25060 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74  ion] D failed, t
25070 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
25080 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72  errcode(D) inter
25090 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
250a0 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
250b0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ult code] or [ex
250c0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
250d0 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20  de] for that.** 
250e0 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20  API call..** If 
250f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
25100 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63  API call was suc
25110 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e  cessful,.** then
25120 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
25130 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65  e from sqlite3_e
25140 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
25150 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  fined..** ^The s
25160 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
25170 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
25180 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
25190 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
251a0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
251b0 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
251c0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
251d0 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
251e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
251f0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
25200 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
25210 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
25220 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
25230 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
25240 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
25250 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
25260 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
25270 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
25280 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
25290 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
252a0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
252b0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
252c0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
252d0 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
252e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
252f0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
25300 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
25310 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
25320 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
25330 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
25340 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
25350 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
25360 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
25370 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
25380 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
25390 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
253a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
253b0 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
253c0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
253d0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
253e0 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
253f0 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
25400 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
25410 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
25420 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
25430 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
25440 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
25450 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
25460 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
25470 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
25480 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
25490 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
254a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
254b0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
254c0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
254d0 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
254e0 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
254f0 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
25500 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
25510 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
25520 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
25530 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
25540 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
25550 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
25560 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
25570 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
25580 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
25590 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
255a0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
255b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
255c0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
255d0 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
255e0 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
255f0 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
25600 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
25610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
25620 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
25630 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
25640 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
25650 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
25660 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
25670 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
25680 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
25690 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
256a0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
256b0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
256c0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
256d0 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
256e0 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
256f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
25700 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
25710 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
25720 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
25730 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
25740 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
25750 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
25760 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
25770 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
25780 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
25790 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
257a0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
257b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
257c0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
257d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
257e0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
257f0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
25800 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
25810 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
25820 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
25830 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
25840 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
25850 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25860 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
25870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72  .** CAPI3REF: Pr
25880 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
25890 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
258a0 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
258b0 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
258c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
258d0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
258e0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
258f0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
25900 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
25910 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62  nt that.** has b
25920 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74  een compiled int
25930 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e  o binary form an
25940 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  d is ready to be
25950 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a   evaluated..**.*
25960 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20  * Think of each 
25970 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
25980 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70   a separate comp
25990 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54  uter program.  T
259a0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
259b0 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63  QL text is sourc
259c0 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61  e code.  A prepa
259d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
259e0 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20  ject .** is the 
259f0 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20  compiled object 
25a00 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d  code.  All SQL m
25a10 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
25a20 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61   into a.** prepa
25a30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65  red statement be
25a40 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72  fore it can be r
25a50 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  un..**.** The li
25a60 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72  fe-cycle of a pr
25a70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25a80 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20   object usually 
25a90 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a  goes like this:.
25aa0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
25ab0 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72  i> Create the pr
25ac0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25ad0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
25ae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
25af0 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  2()]..** <li> Bi
25b00 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61  nd values to [pa
25b10 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
25b20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
25b30 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
25b40 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
25b50 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
25b60 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
25b70 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
25b80 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
25b90 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72  li> Reset the pr
25ba0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25bb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25bc0 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
25bd0 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
25be0 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
25bf0 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
25c00 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
25c10 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
25c20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25c30 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
25c40 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66  </ol>.*/.typedef
25c50 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
25c60 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
25c70 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
25c80 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
25c90 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  its.** METHOD: s
25ca0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54  qlite3.**.** ^(T
25cb0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
25cc0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
25cd0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
25ce0 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
25cf0 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
25d00 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
25d10 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
25d20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
25d30 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
25d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
25d50 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
25d60 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
25d70 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
25d80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
25d90 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
25da0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
25db0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
25dc0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
25dd0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
25de0 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
25df0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
25e00 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
25e10 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
25e20 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
25e30 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
25e40 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
25e50 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
25e60 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
25e70 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
25e80 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
25e90 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
25ea0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
25eb0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
25ec0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
25ed0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
25ee0 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
25ef0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
25f00 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
25f10 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
25f20 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
25f30 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
25f40 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
25f50 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
25f60 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
25f70 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
25f80 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
25f90 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
25fa0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
25fb0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
25fc0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
25fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
25fe0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
25ff0 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
26000 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
26010 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
26020 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
26030 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
26040 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
26050 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
26060 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
26070 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
26080 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
26090 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
260a0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
260b0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
260c0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
260d0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
260e0 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
260f0 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
26100 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
26110 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
26120 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
26130 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
26140 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
26150 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
26160 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
26170 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
26180 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
26190 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
261a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
261b0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
261c0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
261d0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
261e0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
261f0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
26200 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
26210 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
26220 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
26230 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
26240 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
26250 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
26260 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
26270 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
26280 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
26290 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
262a0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
262b0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
262c0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
262d0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
262e0 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
262f0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
26300 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
26310 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
26320 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
26330 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
26340 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
26350 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
26360 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
26370 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
26380 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
26390 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
263a0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
263b0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
263c0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
263d0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
263e0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
263f0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
26400 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
26410 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
26420 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
26430 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
26440 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
26450 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
26460 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
26470 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
26480 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
26490 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
264a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
264b0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
264c0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
264d0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
264e0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
264f0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
26500 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
26510 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
26520 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
26530 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
26540 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
26550 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
26560 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
26570 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
26580 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
26590 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
265a0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
265b0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
265c0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
265d0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
265e0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
265f0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
26600 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
26610 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
26620 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
26630 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
26640 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
26650 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
26660 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26670 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
26680 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
26690 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
266a0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
266b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
266c0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
266d0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
266e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
266f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
26700 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
26710 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
26720 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26730 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26740 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
26750 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
26760 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
26770 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
26780 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
26790 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
267a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
267b0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
267c0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
267d0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
267e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
267f0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
26800 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
26810 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
26820 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
26830 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
26840 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
26850 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
26860 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
26870 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26880 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
26890 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
268a0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
268b0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
268c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
268d0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
268e0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
268f0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
26900 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26910 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
26920 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
26930 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
26940 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26950 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
26960 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
26970 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
26980 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
26990 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
269a0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
269b0 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
269c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
269d0 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
269e0 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
269f0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
26a00 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
26a10 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
26a20 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26a30 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
26a40 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
26a50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
26a60 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
26a70 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26a80 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
26a90 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
26aa0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
26ab0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26ac0 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
26ad0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
26ae0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
26af0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
26b00 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
26b10 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
26b20 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
26b30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26b40 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
26b50 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
26b60 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26b70 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
26b80 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
26b90 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
26ba0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
26bb0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
26bc0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
26bd0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
26be0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26bf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
26c00 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
26c10 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
26c20 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26c30 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
26c40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
26c50 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
26c60 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
26c70 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
26c80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
26c90 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
26ca0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
26cb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
26cc0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
26cd0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26ce0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
26cf0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
26d00 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
26d10 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  [[SQLITE_LIMIT_W
26d20 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20  ORKER_THREADS]] 
26d30 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26d40 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
26d50 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
26d60 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26d70 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f   of auxiliary wo
26d80 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61  rker threads tha
26d90 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70  t a single.** [p
26da0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26db0 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64  t] may start.</d
26dc0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
26dd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26de0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
26df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26e00 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
26e10 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
26e20 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
26e30 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
26e40 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
26e50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26e60 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
26e70 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
26e80 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
26e90 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
26ea0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
26eb0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
26ec0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
26ed0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
26ee0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
26ef0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
26f00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
26f10 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
26f20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
26f30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
26f40 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
26f50 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
26f60 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
26f70 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
26f80 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
26f90 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
26fa0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
26fb0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
26fc0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26fd0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
26fe0 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
26ff0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27000 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20  _WORKER_THREADS 
27010 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
27020 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
27030 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
27040 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
27050 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
27060 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
27070 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
27080 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
27090 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
270a0 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
270b0 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
270c0 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
270d0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
270e0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
270f0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
27100 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
27110 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
27120 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
27130 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
27140 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
27150 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
27160 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
27170 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
27180 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
27190 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
271a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
271b0 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
271c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
271d0 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
271e0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
271f0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
27200 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
27210 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
27220 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
27230 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
27240 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
27250 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
27260 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
27270 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27280 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
27290 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
272a0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
272b0 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
272c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
272d0 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
272e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
272f0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
27300 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
27310 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
27320 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
27330 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
27340 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f   ^If nByte is po
27350 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  sitive, then it 
27360 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
27370 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66   of bytes read f
27380 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e  rom zSql.  ^If n
27390 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68  Byte is zero, th
273a0 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a  en no prepared.*
273b0 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67  * statement is g
273c0 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20  enerated..** If 
273d0 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
273e0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
273f0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
27400 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
27410 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20  n.** there is a 
27420 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63  small performanc
27430 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70  e advantage to p
27440 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
27450 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
27460 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
27470 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
27480 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
27490 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
274a0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
274b0 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tor..**.** ^If p
274c0 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
274d0 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
274e0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
274f0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
27500 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
27510 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
27520 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
27530 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
27540 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
27550 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
27560 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
27570 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
27580 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
27590 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
275a0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
275b0 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
275c0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
275d0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
275e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
275f0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
27600 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
27610 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
27620 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
27630 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
27640 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
27650 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
27660 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
27670 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
27680 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
27690 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
276a0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
276b0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
276c0 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
276d0 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
276e0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
276f0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
27700 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
27710 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
27720 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27730 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
27740 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
27750 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
27760 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
27770 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
27780 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
27790 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
277a0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
277b0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
277c0 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
277d0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
277e0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
277f0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
27800 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
27810 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
27820 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
27830 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
27840 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
27850 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
27860 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
27870 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
27880 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
27890 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
278a0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
278b0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
278c0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
278d0 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
278e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
278f0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
27900 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
27910 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
27920 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
27930 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
27940 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
27950 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
27960 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
27970 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
27980 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
27990 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
279a0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
279b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
279c0 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
279d0 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
279e0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
279f0 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
27a00 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
27a10 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
27a20 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
27a30 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
27a40 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
27a50 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
27a60 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
27a70 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
27a80 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
27a90 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
27aa0 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
27ab0 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
27ac0 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
27ad0 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
27ae0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
27af0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
27b00 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
27b10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27b20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
27b30 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
27b40 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
27b50 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
27b60 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
27b70 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
27b80 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
27b90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27ba0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
27bb0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
27bc0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
27bd0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
27be0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
27bf0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
27c00 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
27c10 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
27c20 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
27c30 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
27c40 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
27c50 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
27c60 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
27c70 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
27c80 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
27c90 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
27ca0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
27cb0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
27cc0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
27cd0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
27ce0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
27cf0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
27d00 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
27d10 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
27d20 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
27d30 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
27d40 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
27d50 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
27d60 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
27d70 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
27d80 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
27d90 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
27da0 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
27db0 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
27dc0 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
27dd0 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
27de0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
27df0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
27e00 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
27e10 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
27e20 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
27e30 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
27e40 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
27e50 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
27e60 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
27e70 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
27e80 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
27e90 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
27ea0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
27eb0 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
27ec0 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
27ed0 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
27ee0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
27ef0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
27f00 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
27f10 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
27f20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
27f30 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
27f40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
27f50 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
27f60 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
27f70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
27f80 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
27f90 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
27fa0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
27fb0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27fc0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
27fd0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
27fe0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
27ff0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
28000 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
28010 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
28020 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
28030 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
28040 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
28050 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
28060 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
28070 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
28080 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
28090 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
280a0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
280b0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
280c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
280d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
280e0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
280f0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
28100 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
28110 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
28120 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
28130 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
28140 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
28150 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
28160 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
28170 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
28180 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
28190 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
281a0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
281b0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
281c0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
281d0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
281e0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
281f0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
28200 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28210 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
28220 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
28230 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
28240 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28250 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28260 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28270 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
28280 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28290 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
282a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
282b0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
282c0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
282d0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
282e0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
282f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28300 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
28310 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28320 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28330 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28340 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
28350 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
28360 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
28370 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
28380 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
28390 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
283a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
283b0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
283c0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
283d0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
283e0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
283f0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
28400 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
28410 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
28420 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
28430 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
28440 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
28450 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
28460 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
28470 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
28480 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
28490 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
284a0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
284b0 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   SQL.** METHOD: 
284c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
284d0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
284e0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
284f0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
28500 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
28510 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
28520 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
28530 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
28540 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
28550 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
28560 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
28570 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
28580 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28590 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
285a0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
285b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
285c0 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
285d0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
285e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
285f0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
28600 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
28610 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
28620 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
28630 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
28640 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
28650 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
28660 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
28670 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
28680 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
28690 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
286a0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
286b0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
286c0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
286d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
286e0 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
286f0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
28700 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28710 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
28720 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
28730 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
28740 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
28750 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
28760 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
28770 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
28780 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
28790 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
287a0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
287b0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
287c0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
287d0 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
287e0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
287f0 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
28800 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
28810 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
28820 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
28830 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
28840 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
28850 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
28860 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
28870 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
28880 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
28890 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
288a0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
288b0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
288c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
288d0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
288e0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
288f0 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
28900 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
28910 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
28920 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
28930 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
28940 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
28950 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
28960 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
28970 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
28980 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
28990 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
289a0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
289b0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
289c0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
289d0 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
289e0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
289f0 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
28a00 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
28a10 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
28a20 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
28a30 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
28a40 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
28a50 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
28a60 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
28a70 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
28a80 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
28a90 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
28aa0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
28ab0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
28ac0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
28ad0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
28ae0 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
28af0 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
28b00 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
28b10 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
28b20 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
28b30 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
28b40 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  sk..*/.int sqlit
28b50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
28b60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
28b70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
28b80 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
28b90 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
28ba0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
28bb0 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48  en Reset.** METH
28bc0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
28bd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28be0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
28bf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28c00 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
28c10 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
28c20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28c30 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
28c40 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
28c50 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
28c60 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
28c70 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
28c80 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
28c90 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
28ca0 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
28cb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28cc0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
28cd0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
28ce0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
28cf0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
28d00 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
28d10 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
28d20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
28d30 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
28d40 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
28d50 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
28d60 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
28d70 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
28d80 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
28d90 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
28da0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
28db0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
28dc0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
28dd0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
28de0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
28df0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
28e00 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
28e10 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
28e20 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
28e30 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
28e40 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
28e50 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
28e60 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
28e70 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
28e80 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
28e90 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
28ea0 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
28eb0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
28ec0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
28ed0 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
28ee0 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
28ef0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
28f00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
28f10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28f20 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
28f30 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
28f40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
28f50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28f60 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
28f70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28f80 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
28f90 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
28fa0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
28fb0 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
28fc0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
28fd0 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
28fe0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
28ff0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
29000 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
29010 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
29020 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
29030 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
29040 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29050 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
29060 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
29070 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
29080 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
29090 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
290a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
290b0 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
290c0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
290d0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
290e0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
290f0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
29100 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29110 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
29120 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
29130 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
29140 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
29150 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29160 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
29170 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
29180 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
29190 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
291a0 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
291b0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
291c0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
291d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
291e0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
291f0 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
29200 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
29210 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
29220 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
29230 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
29240 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
29250 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
29260 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
29270 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29280 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
29290 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
292a0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
292b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
292c0 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
292d0 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
292e0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
292f0 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
29300 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
29310 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
29320 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
29330 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
29340 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
29350 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
29360 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
29370 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
29380 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
29390 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
293a0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
293b0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
293c0 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
293d0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
293e0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
293f0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
29400 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
29410 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
29420 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
29430 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
29440 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
29450 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
29460 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
29470 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
29480 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
29490 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
294a0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
294b0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
294c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
294d0 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
294e0 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
294f0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
29500 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
29510 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
29520 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
29530 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
29540 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
29550 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
29560 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29570 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
29580 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
29590 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
295a0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
295b0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
295c0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
295d0 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
295e0 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
295f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29600 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
29610 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
29620 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
29630 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
29640 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
29650 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
29660 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
29670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
29680 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
29690 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
296a0 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
296b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
296c0 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
296d0 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
296e0 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
296f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
29700 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
29710 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
29720 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
29730 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
29740 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
29750 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
29760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
29770 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
29780 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
29790 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
297a0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
297b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
297c0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
297d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
297e0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
297f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29800 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
29810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
29820 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
29830 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
29840 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
29850 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
29860 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
29870 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
29880 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
29890 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
298a0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
298b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
298c0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
298d0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
298e0 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
298f0 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
29900 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
29910 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
29920 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
29930 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
29940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29950 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
29960 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
29970 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
29980 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
29990 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
299a0 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
299b0 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
299c0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
299d0 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
299e0 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
299f0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
29a00 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
29a10 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49  3_stmt.**.** ^(I
29a20 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
29a30 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
29a40 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
29a50 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
29a60 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
29a70 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
29a80 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
29a90 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
29aa0 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
29ab0 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
29ac0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
29ad0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
29ae0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
29af0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
29b00 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
29b10 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
29b20 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
29b30 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
29b40 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
29b50 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
29b60 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
29b70 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
29b80 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
29b90 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
29ba0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
29bb0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
29bc0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
29bd0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
29be0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
29bf0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
29c00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29c10 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
29c20 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
29c30 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
29c40 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
29c50 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
29c60 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
29c70 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
29c80 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
29c90 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
29ca0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
29cb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29cc0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
29cd0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
29ce0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
29cf0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
29d00 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
29d10 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
29d20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
29d30 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
29d40 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
29d50 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
29d60 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
29d70 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
29d80 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
29d90 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
29da0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
29db0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
29dc0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
29dd0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
29de0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
29df0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
29e00 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
29e10 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
29e20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29e30 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
29e40 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
29e50 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
29e60 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
29e70 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
29e80 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
29e90 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
29ea0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
29eb0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
29ec0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
29ed0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
29ee0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
29ef0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
29f00 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
29f10 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
29f20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
29f30 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
29f40 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
29f50 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
29f60 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
29f70 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
29f80 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
29f90 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
29fa0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
29fb0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
29fc0 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
29fd0 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
29fe0 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
29ff0 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
2a000 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
2a010 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2a020 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
2a030 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
2a040 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
2a050 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
2a060 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2a070 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2a080 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
2a090 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
2a0a0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
2a0b0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
2a0c0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
2a0d0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
2a0e0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2a0f0 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
2a100 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a110 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2a120 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2a130 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2a140 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
2a150 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
2a160 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
2a170 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
2a180 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
2a190 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2a1a0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
2a1b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2a1c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2a1d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2a1e0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
2a1f0 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
2a200 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2a210 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
2a220 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
2a230 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
2a240 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a250 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
2a260 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2a270 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2a280 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e  nd_text64() then
2a290 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74  .** that paramet
2a2a0 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
2a2b0 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
2a2c0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
2a2d0 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
2a2e0 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
2a2f0 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
2a300 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
2a310 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
2a320 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
2a330 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
2a340 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
2a350 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
2a360 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
2a370 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
2a380 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
2a390 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
2a3a0 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
2a3b0 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
2a3c0 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
2a3d0 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
2a3e0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
2a3f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2a400 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2a410 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f  ument to the BLO
2a420 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e  B and string bin
2a430 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a  ding interfaces.
2a440 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ** is a destruct
2a450 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
2a460 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2a470 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
2a480 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
2a490 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
2a4a0 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
2a4b0 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
2a4c0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2a4d0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
2a4e0 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
2a4f0 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73  o bind API fails
2a500 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2a510 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
2a520 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
2a530 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
2a540 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
2a550 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2a560 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
2a570 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
2a580 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
2a590 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
2a5a0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
2a5b0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2a5c0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
2a5d0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
2a5e0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
2a5f0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
2a600 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2a610 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
2a620 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
2a630 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
2a640 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2a650 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
2a660 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72  ** ^The sixth ar
2a670 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2a680 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2a690 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a  must be one of.*
2a6a0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  * [SQLITE_UTF8],
2a6b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
2a6c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2a6d0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
2a6e0 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65  F16LE].** to spe
2a6f0 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e  cify the encodin
2a700 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e  g of the text in
2a710 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2a720 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  eter.  If.** the
2a730 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2a740 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a750 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20  text64() is not 
2a760 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c  one of the.** al
2a770 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f  lowed values sho
2a780 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20  wn above, or if 
2a790 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2a7a0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a  g is different.*
2a7b0 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64  * from the encod
2a7c0 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79  ing specified by
2a7d0 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
2a7e0 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62  eter, then the b
2a7f0 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
2a800 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2a810 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2a820 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
2a830 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
2a840 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
2a850 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
2a860 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
2a870 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
2a880 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
2a890 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
2a8a0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
2a8b0 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
2a8c0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
2a8d0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
2a8e0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
2a8f0 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
2a900 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2a910 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2a920 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2a930 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2a940 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2a950 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2a960 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2a970 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2a980 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2a990 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2a9a0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2a9b0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2a9c0 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
2a9d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2a9e0 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
2a9f0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
2aa00 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
2aa10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2aa20 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
2aa30 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
2aa40 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
2aa50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2aa60 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
2aa70 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
2aa80 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
2aa90 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
2aaa0 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
2aab0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2aac0 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
2aad0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
2aae0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
2aaf0 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
2ab00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2ab10 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2ab20 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
2ab30 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2ab40 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
2ab50 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
2ab60 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
2ab70 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
2ab80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ab90 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
2aba0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
2abb0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
2abc0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
2abd0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2abe0 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
2abf0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
2ac00 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
2ac10 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
2ac20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
2ac30 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
2ac40 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68  ITE_TOOBIG] migh
2ac50 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
2ac60 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73   the size of a s
2ac70 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a  tring or BLOB.**
2ac80 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20   exceeds limits 
2ac90 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69  imposed by [sqli
2aca0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2acb0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2acc0 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ) or.** [SQLITE_
2acd0 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20  MAX_LENGTH]..** 
2ace0 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
2acf0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
2ad00 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2ad10 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2ad20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
2ad30 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
2ad40 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
2ad50 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
2ad60 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2ad70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2ad80 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
2ad90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ada0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2adb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2adc0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2add0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2ade0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
2adf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2ae00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2ae10 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2ae20 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2ae30 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c  _bind_blob64(sql
2ae40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2ae50 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71   const void*, sq
2ae60 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2ae70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ae80 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2ae90 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2aea0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
2aeb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2aec0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
2aed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2aee0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aef0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
2af00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
2af10 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2af20 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
2af30 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
2af40 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
2af50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2af60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2af70 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
2af80 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  tmt*,int,const c
2af90 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29  har*,int,void(*)
2afa0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2afb0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2afc0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2afd0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2afe0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2aff0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2b000 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2b010 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b020 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
2b030 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2b040 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2b050 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2b060 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
2b070 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
2b080 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  g);.int sqlite3_
2b090 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
2b0a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2b0b0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
2b0c0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2b0d0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2b0e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b0f0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
2b100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2b110 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
2b120 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eters.** METHOD:
2b130 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2b140 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2b150 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2b160 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2b170 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2b180 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2b190 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b1a0 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2b1b0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2b1c0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2b1d0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2b1e0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2b1f0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2b200 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2b210 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2b220 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2b230 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2b240 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2b250 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2b260 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2b270 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2b280 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2b290 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2b2a0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2b2b0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2b2c0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2b2d0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2b2e0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2b2f0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2b300 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2b310 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2b320 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2b330 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2b340 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2b350 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2b360 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2b370 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2b380 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2b390 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2b3a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b3b0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2b3c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2b3d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2b3e0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2b3f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b400 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2b410 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2b420 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2b430 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2b440 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eter.** METHOD: 
2b450 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b460 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b470 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2b480 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
2b490 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
2b4a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
2b4b0 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
2b4c0 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
2b4d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2b4e0 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
2b4f0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2b500 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
2b510 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2b520 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
2b530 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
2b540 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
2b550 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2b560 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2b570 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
2b580 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2b590 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
2b5a0 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
2b5b0 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
2b5c0 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
2b5d0 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
2b5e0 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
2b5f0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
2b600 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
2b610 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
2b620 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
2b630 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
2b640 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
2b650 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
2b660 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
2b670 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
2b680 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2b690 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
2b6a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
2b6b0 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
2b6c0 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
2b6d0 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
2b6e0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
2b6f0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
2b700 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
2b710 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
2b720 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
2b730 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
2b740 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
2b750 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
2b760 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
2b770 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2b780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b790 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
2b7a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2b7b0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2b7c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2b7d0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2b7e0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2b7f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b800 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2b810 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2b820 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2b830 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
2b840 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
2b850 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2b860 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2b870 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
2b880 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
2b890 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
2b8a0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
2b8b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2b8c0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2b8d0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2b8e0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2b8f0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2b900 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2b910 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2b920 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2b930 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2b940 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2b950 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2b960 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2b970 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2b980 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2b990 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2b9a0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2b9b0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2b9c0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2b9d0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2b9e0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2b9f0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2ba00 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2ba10 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2ba20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2ba30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ba40 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2ba50 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2ba60 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2ba70 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2ba80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ba90 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2baa0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2bab0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2bac0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2bad0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bae0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2baf0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2bb00 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2bb10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2bb20 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2bb30 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2bb40 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2bb50 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2bb60 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
2bb70 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
2bb80 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
2bb90 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
2bba0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
2bbb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bbc0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
2bbd0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2bbe0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
2bbf0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2bc00 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
2bc10 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
2bc20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
2bc30 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2bc40 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2bc50 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2bc60 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
2bc70 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
2bc80 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt Set.** METHOD
2bc90 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2bca0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2bcb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2bcc0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
2bcd0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
2bce0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2bcf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
2bd00 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2bd10 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
2bd20 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
2bd30 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
2bd40 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
2bd50 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
2bd60 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
2bd70 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2bd80 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
2bd90 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2bda0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2bdb0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2bdc0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2bdd0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2bde0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2bdf0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2be00 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2be10 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2be20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2be30 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
2be40 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
2be50 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
2be60 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
2be70 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
2be80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2be90 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
2bea0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2beb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2bec0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2bed0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
2bee0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2bef0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
2bf00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2bf10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2bf20 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
2bf30 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
2bf40 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2bf50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bf60 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
2bf70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
2bf80 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2bf90 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2bfa0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2bfb0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
2bfc0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2bfd0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
2bfe0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
2bff0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
2c000 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
2c010 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
2c020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c030 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
2c040 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
2c050 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2c060 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2c070 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2c080 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2c090 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2c0a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c0b0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2c0c0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2c0d0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
2c0e0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
2c0f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2c100 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2c110 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
2c120 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
2c130 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
2c140 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
2c150 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
2c160 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
2c170 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
2c180 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
2c190 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
2c1a0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
2c1b0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
2c1c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2c1d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2c1e0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
2c1f0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
2c200 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2c210 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
2c220 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
2c230 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
2c240 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
2c250 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
2c260 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
2c270 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
2c280 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
2c290 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
2c2a0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
2c2b0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
2c2c0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
2c2d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2c2e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
2c2f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c300 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
2c310 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c320 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2c330 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2c340 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c350 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2c360 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2c370 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c380 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c390 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2c3a0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2c3b0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2c3c0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2c3d0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2c3e0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2c3f0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2c400 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2c410 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2c420 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2c430 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2c440 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2c450 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2c460 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2c470 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2c480 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2c490 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2c4a0 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2c4b0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2c4c0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2c4d0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2c4e0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2c4f0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2c500 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2c510 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2c520 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2c530 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2c540 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2c550 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2c560 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2c570 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2c580 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2c590 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2c5a0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2c5b0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2c5c0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2c5d0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2c5e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2c5f0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2c600 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2c610 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2c620 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2c630 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2c640 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2c650 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2c660 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2c670 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2c680 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2c690 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2c6a0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2c6b0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2c6c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2c6d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2c6e0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2c6f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c700 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2c710 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2c720 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2c730 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2c740 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2c750 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2c760 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2c770 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2c780 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2c790 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2c7a0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2c7b0 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2c7c0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2c7d0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2c7e0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2c7f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c800 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2c810 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2c820 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2c830 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2c840 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2c850 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2c860 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2c870 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2c880 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2c890 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2c8a0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2c8b0 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2c8c0 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2c8d0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2c8e0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2c8f0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2c900 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2c910 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2c920 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2c930 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2c940 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2c950 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2c960 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2c970 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2c980 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2c990 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2c9a0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2c9b0 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2c9c0 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2c9d0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2c9e0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2c9f0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2ca00 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2ca10 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2ca20 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2ca30 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2ca40 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2ca50 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2ca60 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2ca70 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2ca80 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2ca90 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2caa0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2cab0 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2cac0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2cad0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2cae0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2caf0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2cb00 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2cb10 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2cb20 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2cb30 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2cb40 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2cb50 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2cb60 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2cb70 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2cb80 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2cb90 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2cba0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2cbb0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2cbc0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2cbd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2cbe0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2cbf0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2cc00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2cc10 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2cc20 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2cc30 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2cc40 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2cc50 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2cc60 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2cc70 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2cc80 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2cc90 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2cca0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2ccb0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2ccc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2ccd0 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
2cce0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2ccf0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2cd00 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2cd10 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2cd20 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2cd30 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2cd40 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2cd50 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2cd60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2cd70 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2cd80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2cd90 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
2cda0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2cdb0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
2cdc0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
2cdd0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
2cde0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2cdf0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
2ce00 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
2ce10 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
2ce20 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
2ce30 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
2ce40 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2ce50 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
2ce60 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
2ce70 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
2ce80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
2ce90 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2cea0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2ceb0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
2cec0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2ced0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
2cee0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2cef0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
2cf00 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2cf10 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
2cf20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
2cf30 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
2cf40 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
2cf50 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
2cf60 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
2cf70 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
2cf80 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
2cf90 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
2cfa0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
2cfb0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
2cfc0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
2cfd0 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
2cfe0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
2cff0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
2d000 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
2d010 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
2d020 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
2d030 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
2d040 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
2d050 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
2d060 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
2d070 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2d080 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
2d090 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
2d0a0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
2d0b0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
2d0c0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
2d0d0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
2d0e0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
2d0f0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
2d100 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
2d110 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
2d120 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
2d130 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
2d140 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
2d150 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
2d160 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
2d170 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
2d180 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
2d190 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
2d1a0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
2d1b0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
2d1c0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
2d1d0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2d1e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2d1f0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
2d200 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2d210 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2d220 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2d230 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d240 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2d250 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2d260 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2d270 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2d280 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
2d290 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2d2a0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2d2b0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2d2c0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2d2d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d2e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2d2f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2d300 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2d310 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2d320 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2d330 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2d340 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2d350 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2d360 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2d370 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2d380 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2d390 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2d3a0 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2d3b0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2d3c0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2d3d0 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2d3e0 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2d3f0 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2d400 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2d410 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2d420 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2d430 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2d440 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2d450 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2d460 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2d470 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2d480 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2d490 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2d4a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d4b0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2d4c0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2d4d0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2d4e0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2d4f0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2d500 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2d510 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2d520 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2d530 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2d540 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2d550 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2d560 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2d570 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2d580 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2d590 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2d5a0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2d5b0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2d5c0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2d5d0 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2d5e0 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2d5f0 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2d600 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2d610 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2d620 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2d630 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2d640 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2d650 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2d660 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2d670 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2d680 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2d690 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2d6a0 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2d6b0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2d6c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2d6d0 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2d6e0 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2d6f0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2d700 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2d710 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2d720 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2d730 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2d740 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2d750 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2d760 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2d770 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2d780 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2d790 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2d7a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2d7b0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2d7c0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2d7d0 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2d7e0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2d7f0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2d800 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2d810 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2d820 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2d830 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2d840 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2d850 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2d860 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2d870 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2d880 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2d890 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2d8a0 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2d8b0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2d8c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2d8d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2d8e0 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2d8f0 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2d900 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2d910 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2d920 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2d930 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2d940 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2d950 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2d960 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2d970 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2d980 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2d990 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2d9a0 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2d9b0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2d9c0 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2d9d0 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2d9e0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2d9f0 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2da00 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2da10 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2da20 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2da30 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2da40 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2da50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2da60 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2da70 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2da80 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2da90 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2daa0 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2dab0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2dac0 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2dad0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2dae0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2daf0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2db00 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2db10 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2db20 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2db30 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2db40 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2db50 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2db60 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2db70 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2db80 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2db90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dba0 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2dbb0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2dbc0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2dbd0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2dbe0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2dbf0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2dc00 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2dc10 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2dc20 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2dc30 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2dc40 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2dc50 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2dc60 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2dc70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dc80 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2dc90 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2dca0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2dcb0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2dcc0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2dcd0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2dce0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2dcf0 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2dd00 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2dd10 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2dd20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2dd30 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2dd40 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2dd50 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2dd60 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2dd70 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2dd80 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2dd90 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2dda0 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2ddb0 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2ddc0 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2ddd0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2dde0 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2ddf0 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2de00 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2de10 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2de20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2de30 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2de40 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2de50 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2de60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2de70 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2de80 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2de90 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2dea0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2deb0 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2dec0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2ded0 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2dee0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2def0 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2df00 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2df10 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2df20 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2df30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2df40 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2df50 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2df60 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2df70 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2df80 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2df90 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2dfa0 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2dfb0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2dfc0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2dfd0 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2dfe0 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2dff0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2e000 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2e010 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2e020 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2e030 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2e040 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2e050 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2e060 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2e070 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2e080 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2e090 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2e0a0 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2e0b0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2e0c0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2e0d0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2e0e0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2e0f0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2e100 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2e110 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2e120 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2e130 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2e140 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2e150 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2e160 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e170 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2e180 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2e190 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2e1a0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2e1b0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2e1c0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2e1d0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2e1e0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2e1f0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2e200 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2e210 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2e220 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2e230 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2e240 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2e250 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2e260 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2e270 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2e280 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e290 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2e2a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2e2b0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2e2c0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2e2d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2e2e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2e2f0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2e300 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2e310 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2e320 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2e330 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2e340 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2e350 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2e360 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2e370 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2e380 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
2e390 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2e3a0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2e3b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2e3c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2e3d0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2e3e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e3f0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e400 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2e410 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
2e420 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2e430 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2e440 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
2e450 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2e460 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
2e470 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e480 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
2e490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2e4a0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
2e4b0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
2e4c0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
2e4d0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
2e4e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
2e4f0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
2e500 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
2e510 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
2e520 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e530 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
2e540 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2e550 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2e560 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
2e570 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
2e580 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
2e590 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2e5a0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2e5b0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
2e5c0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2e5d0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2e5e0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2e5f0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2e600 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2e610 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
2e620 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
2e630 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
2e640 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2e650 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2e660 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
2e670 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
2e680 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
2e690 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
2e6a0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
2e6b0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
2e6c0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
2e6d0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
2e6e0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
2e6f0 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
2e700 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
2e710 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2e720 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
2e730 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
2e740 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
2e750 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2e760 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2e770 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
2e780 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
2e790 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
2e7a0 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
2e7b0 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
2e7c0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
2e7d0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
2e7e0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
2e7f0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2e800 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
2e810 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
2e820 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
2e830 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2e840 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
2e850 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
2e860 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
2e870 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
2e880 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
2e890 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
2e8a0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
2e8b0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2e8c0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
2e8d0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
2e8e0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
2e8f0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
2e900 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
2e910 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
2e920 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
2e930 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
2e940 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
2e950 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
2e960 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
2e970 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
2e980 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
2e990 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
2e9a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
2e9b0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
2e9c0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
2e9d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e9e0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
2e9f0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
2ea00 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
2ea10 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
2ea20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
2ea30 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
2ea40 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
2ea50 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
2ea60 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
2ea70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ea80 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
2ea90 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
2eaa0 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
2eab0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2eac0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
2ead0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2eae0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2eaf0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2eb00 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2eb10 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2eb20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2eb30 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2eb40 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2eb50 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2eb60 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2eb70 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2eb80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2eb90 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2eba0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2ebb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2ebc0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2ebd0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2ebe0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2ebf0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2ec00 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2ec10 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2ec20 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2ec30 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2ec40 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2ec50 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2ec60 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2ec70 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2ec80 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2ec90 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2eca0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2ecb0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2ecc0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2ecd0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2ece0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2ecf0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2ed00 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2ed10 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2ed20 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2ed30 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2ed40 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2ed50 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2ed60 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2ed70 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2ed80 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2ed90 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2eda0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2edb0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2edc0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2edd0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2ede0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2edf0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2ee00 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2ee10 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2ee20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2ee30 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2ee40 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2ee50 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2ee60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2ee70 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2ee80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2ee90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2eea0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2eeb0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2eec0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2eed0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2eee0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2eef0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2ef00 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2ef10 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2ef20 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2ef30 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2ef40 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2ef50 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2ef60 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2ef70 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2ef80 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2ef90 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2efa0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2efb0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2efc0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2efd0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2efe0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2eff0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2f000 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2f010 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2f020 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2f030 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2f040 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2f050 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2f060 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2f070 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2f080 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2f090 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2f0a0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2f0b0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2f0c0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2f0d0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2f0e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2f0f0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2f100 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2f110 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2f120 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2f130 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2f140 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2f150 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2f160 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2f170 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2f180 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2f190 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2f1a0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2f1b0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2f1c0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2f1d0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2f1e0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2f1f0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2f200 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2f210 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f220 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2f230 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2f240 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2f250 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2f260 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2f270 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f280 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2f290 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2f2a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f2b0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2f2c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2f2d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2f2e0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2f2f0 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2f300 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2f310 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f320 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2f330 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2f340 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2f350 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f360 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2f370 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2f380 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2f390 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2f3a0 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2f3b0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2f3c0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2f3d0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2f3e0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f3f0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2f400 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f410 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2f420 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2f430 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2f440 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2f450 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2f460 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f470 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2f480 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2f490 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2f4a0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2f4b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2f4c0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
2f4d0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2f4e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f4f0 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
2f500 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2f510 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
2f520 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2f530 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2f540 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f550 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2f560 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2f570 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
2f580 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2f590 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2f5a0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2f5b0 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
2f5c0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2f5d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2f5e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2f5f0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2f600 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2f610 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2f620 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f630 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2f640 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
2f650 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2f660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f670 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
2f680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f690 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
2f6a0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2f6b0 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
2f6c0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
2f6d0 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
2f6e0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2f6f0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
2f700 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2f710 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2f720 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f730 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
2f740 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2f750 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2f760 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2f770 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2f780 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
2f790 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2f7a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f7b0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
2f7c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
2f7d0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
2f7e0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
2f7f0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
2f800 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2f810 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2f820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2f830 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2f840 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2f850 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2f860 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a  *.** <b>Warning:
2f870 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74  </b> ^The object
2f880 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2f890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2f8a0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
2f8b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2f8c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2f8d0 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68  t.  In a multith
2f8e0 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65  readed environme
2f8f0 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74  nt,.** an unprot
2f900 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2f910 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f  lue object may o
2f920 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65  nly be used safe
2f930 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ly with.** [sqli
2f940 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2f950 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2f960 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
2f970 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
2f980 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f990 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
2f9a0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2f9b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2f9c0 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
2f9d0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
2f9e0 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
2f9f0 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
2fa00 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
2fa10 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
2fa20 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2fa30 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2fa40 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2fa50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2fa60 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
2fa70 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2fa80 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
2fa90 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2faa0 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
2fab0 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
2fac0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
2fad0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
2fae0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
2faf0 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
2fb00 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
2fb10 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
2fb20 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
2fb30 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
2fb40 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
2fb50 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
2fb60 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
2fb70 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
2fb80 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
2fb90 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
2fba0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
2fbb0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
2fbc0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
2fbd0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
2fbe0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
2fbf0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
2fc00 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
2fc10 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
2fc20 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2fc30 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2fc40 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2fc50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2fc60 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
2fc70 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2fc80 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
2fc90 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2fca0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2fcb0 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
2fcc0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2fcd0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2fce0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2fcf0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
2fd00 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2fd10 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2fd20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2fd30 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2fd40 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2fd50 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2fd60 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2fd70 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2fd80 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2fd90 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2fda0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2fdb0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2fdc0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2fdd0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2fde0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2fdf0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2fe00 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2fe10 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2fe20 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2fe30 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2fe40 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2fe50 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
2fe60 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2fe70 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2fe80 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
2fe90 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
2fea0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2feb0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2fec0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2fed0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2fee0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2fef0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2ff00 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
2ff10 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2ff20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
2ff30 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
2ff40 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2ff50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2ff60 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2ff70 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2ff80 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
2ff90 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
2ffa0 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
2ffb0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2ffc0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2ffd0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2ffe0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2fff0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
30000 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
30010 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
30020 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
30030 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
30040 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
30050 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
30060 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
30070 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
30080 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30090 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
300a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
300b0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
300c0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
300d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
300e0 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
300f0 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
30100 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
30110 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
30120 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
30130 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
30140 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
30150 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
30160 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
30170 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
30180 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
30190 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
301a0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
301b0 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
301c0 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
301d0 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
301e0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
301f0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
30200 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
30210 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30220 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
30230 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
30240 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
30250 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
30260 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
30270 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
30280 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
30290 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
302a0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
302b0 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
302c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
302d0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
302e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
302f0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
30300 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
30310 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
30320 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
30330 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
30340 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
30350 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
30360 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
30370 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
30380 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
30390 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
303a0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
303b0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
303c0 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
303d0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
303e0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
303f0 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
30400 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
30410 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
30420 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
30430 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
30440 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
30450 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
30460 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
30470 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
30480 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
30490 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
304a0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
304b0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
304c0 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79  he safest policy
304d0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
304e0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
304f0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
30500 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
30510 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
30520 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
30530 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
30540 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
30550 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
30560 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
30570 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
30580 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
30590 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
305a0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
305b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
305c0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
305d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
305e0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
305f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
30600 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
30610 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
30620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30630 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
30640 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
30650 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
30660 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
30670 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
30680 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
30690 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
306a0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
306b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
306c0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
306d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
306e0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
306f0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
30700 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
30710 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
30720 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30730 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
30740 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
30750 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
30760 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30770 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
30780 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
30790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
307a0 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
307b0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
307c0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
307d0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
307e0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
307f0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
30800 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
30810 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
30820 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
30830 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
30840 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
30850 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
30860 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30870 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
30880 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
30890 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
308a0 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
308b0 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
308c0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
308d0 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73  <em>not</em> pas
308e0 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
308f0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
30900 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30910 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
30920 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
30930 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
30940 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
30950 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
30960 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
30970 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
30980 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
30990 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
309a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
309b0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
309c0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
309d0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
309e0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
309f0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
30a00 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
30a10 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
30a20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
30a30 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
30a40 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
30a50 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
30a60 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
30a70 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
30a80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
30a90 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
30aa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30ab0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
30ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30ad0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30ae0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
30af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30b00 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
30b10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30b20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
30b30 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
30b40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30b50 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
30b60 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
30b70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30b80 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
30b90 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
30ba0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
30bb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30bc0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
30bd0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
30be0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
30bf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30c00 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
30c10 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
30c20 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
30c30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30c40 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
30c50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
30c60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30c70 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
30c80 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
30c90 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
30ca0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30cb0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
30cc0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
30cd0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
30ce0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54  t Object.** DEST
30cf0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
30d00 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
30d10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30d20 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
30d30 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
30d40 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
30d50 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
30d60 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
30d70 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
30d80 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
30d90 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
30da0 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
30db0 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
30dc0 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
30dd0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
30de0 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
30df0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
30e00 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
30e10 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
30e20 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
30e30 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
30e40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
30e50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
30e60 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
30e70 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
30e80 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
30e90 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
30ea0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30eb0 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
30ec0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
30ed0 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
30ee0 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
30ef0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
30f00 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
30f10 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
30f20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
30f30 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
30f40 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
30f50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30f60 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
30f70 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
30f80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
30f90 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
30fa0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
30fb0 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
30fc0 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
30fd0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
30fe0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
30ff0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
31000 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
31010 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
31020 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
31030 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
31040 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
31050 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
31060 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
31070 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
31080 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
31090 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
310a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
310b0 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
310c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
310d0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
310e0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
310f0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
31100 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
31110 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
31120 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
31130 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
31140 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
31150 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
31160 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
31170 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
31180 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
31190 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
311a0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
311b0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
311c0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
311d0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
311e0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
311f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
31200 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  stmt.**.** The s
31210 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
31220 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
31230 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
31240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31250 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
31260 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
31270 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
31280 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
31290 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
312a0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
312b0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
312c0 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
312d0 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
312e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
312f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
31300 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
31310 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
31320 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
31330 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
31340 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
31350 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
31360 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
31370 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
31380 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
31390 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
313a0 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
313b0 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
313c0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
313d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
313e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
313f0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
31400 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
31410 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
31420 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
31430 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
31440 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
31450 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
31460 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
31470 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
31480 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
31490 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
314a0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
314b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
314c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
314d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
314e0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
314f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
31500 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
31510 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
31520 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
31530 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
31540 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
31550 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
31560 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
31570 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
31580 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
31590 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
315a0 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
315b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
315c0 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
315d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
315e0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
315f0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
31600 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
31610 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31620 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
31630 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
31640 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
31650 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
31660 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
31670 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
31680 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
31690 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
316a0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
316b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
316c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
316d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
316e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
316f0 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
31700 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
31710 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
31720 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
31730 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
31740 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
31750 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
31760 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
31770 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
31780 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
31790 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
317a0 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
317b0 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
317c0 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
317d0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
317e0 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
317f0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
31800 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
31810 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
31820 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
31830 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
31840 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
31850 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
31860 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
31870 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
31880 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
31890 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
318a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
318b0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
318c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
318d0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
318e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
318f0 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
31900 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
31910 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
31920 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
31930 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
31940 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31950 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
31960 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
31970 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
31980 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
31990 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
319a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
319b0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
319c0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
319d0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
319e0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
319f0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
31a00 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
31a10 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
31a20 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
31a30 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
31a40 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
31a50 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
31a60 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
31a70 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
31a80 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
31a90 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
31aa0 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
31ab0 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
31ac0 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
31ad0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
31ae0 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
31af0 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
31b00 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
31b10 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
31b20 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
31b30 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
31b40 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
31b50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
31b60 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
31b70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
31b80 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
31b90 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
31ba0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
31bb0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
31bc0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
31bd0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
31be0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
31bf0 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
31c00 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
31c10 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
31c20 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
31c30 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
31c40 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
31c50 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
31c60 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
31c70 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
31c80 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
31c90 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
31ca0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
31cb0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
31cc0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
31cd0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
31ce0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
31cf0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
31d00 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
31d10 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
31d20 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
31d30 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
31d40 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69  n should set thi
31d50 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
31d60 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
31d70 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69  E] if the functi
31d80 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
31d90 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73  n invokes .** [s
31da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31db0 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16le()] on an i
31dc0 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45  nput, or [SQLITE
31dd0 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65  _UTF16BE] if the
31de0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
31df0 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  on invokes [sqli
31e00 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31e10 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  be()] on an inpu
31e20 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  t, or.** [SQLITE
31e30 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69  _UTF16] if [sqli
31e40 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31e50 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20  ()] is used, or 
31e60 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a  [SQLITE_UTF8].**
31e70 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68   otherwise.  ^Th
31e80 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
31e90 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
31ea0 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
31eb0 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69  imes using.** di
31ec0 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65  fferent preferre
31ed0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
31ee0 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  , with different
31ef0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
31f00 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63   for.** each enc
31f10 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20  oding..** ^When 
31f20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
31f30 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
31f40 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
31f50 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
31f60 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
31f70 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
31f80 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
31f90 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
31fa0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
31fb0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
31fc0 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69  rameter may opti
31fd0 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77  onally be ORed w
31fe0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  ith [SQLITE_DETE
31ff0 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f  RMINISTIC].** to
32000 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
32010 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61   function will a
32020 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
32030 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76   same result giv
32040 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69  en.** the same i
32050 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73  nputs within a s
32060 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
32070 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66  ent.  Most SQL f
32080 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20  unctions are.** 
32090 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
320a0 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61  The built-in [ra
320b0 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63  ndom()] SQL func
320c0 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70  tion is an examp
320d0 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74  le of a.** funct
320e0 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ion that is not 
320f0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
32100 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79  The SQLite query
32110 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65   planner is able
32120 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61   to.** perform a
32130 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69  dditional optimi
32140 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72  zations on deter
32150 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f  ministic functio
32160 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66  ns, so use.** of
32170 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54   the [SQLITE_DET
32180 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67  ERMINISTIC] flag
32190 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
321a0 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
321b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
321c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
321d0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
321e0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
321f0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
32200 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
32210 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
32220 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
32230 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
32240 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
32250 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
32260 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
32270 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
32280 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
32290 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
322a0 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
322b0 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
322c0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
322d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
322e0 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
322f0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
32300 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
32310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32320 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
32330 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
32340 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
32350 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
32360 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
32370 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
32380 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
32390 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
323a0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
323b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
323c0 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
323d0 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
323e0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
323f0 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
32400 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
32410 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
32420 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
32430 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
32440 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
32450 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
32460 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
32470 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
32480 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
32490 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
324a0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
324b0 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
324c0 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
324d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
324e0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
324f0 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
32500 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
32510 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
32520 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
32530 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
32540 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
32550 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
32560 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
32570 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
32580 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
32590 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
325a0 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
325b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
325c0 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
325d0 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
325e0 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
325f0 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
32600 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
32610 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
32620 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
32630 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
32640 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
32650 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
32660 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
32670 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
32680 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
32690 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
326a0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
326b0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
326c0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
326d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
326e0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
326f0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
32700 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
32710 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
32720 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
32730 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
32740 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
32750 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
32760 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
32770 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
32780 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
32790 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
327a0 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
327b0 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
327c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
327d0 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
327e0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
327f0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
32800 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
32810 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
32820 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
32830 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32840 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
32850 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
32860 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
32870 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
32880 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
32890 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
328a0 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
328b0 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
328c0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
328d0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
328e0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
328f0 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
32900 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
32910 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
32920 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
32930 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
32940 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
32950 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
32960 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
32970 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
32980 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
32990 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
329a0 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
329b0 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
329c0 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
329d0 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
329e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
329f0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
32a00 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
32a10 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32a20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
32a30 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
32a40 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
32a50 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
32a60 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
32a70 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
32a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32a90 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
32aa0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
32ab0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
32ac0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
32ad0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32ae0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32af0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32b00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
32b10 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32b20 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
32b30 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
32b40 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
32b50 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
32b60 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
32b70 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32b80 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32b90 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
32ba0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32bb0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32bc0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32bd0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
32be0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
32bf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32c00 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
32c10 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
32c20 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
32c30 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
32c40 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
32c50 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
32c60 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
32c70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32c80 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32c90 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32ca0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
32cb0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32cc0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32cd0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
32ce0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32cf0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
32d00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32d10 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
32d20 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
32d30 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
32d40 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
32d50 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
32d60 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
32d70 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
32d80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
32d90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
32da0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
32db0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32dc0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32dd0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32de0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
32df0 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
32e00 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
32e10 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
32e20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
32e30 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
32e40 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
32e50 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
32e60 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
32e70 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
32e80 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
32e90 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
32ea0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
32eb0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
32ec0 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d        1    /* IM
32ed0 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36  P: R-37514-35566
32ee0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
32ef0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
32f00 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    2    /* IMP: R
32f10 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a  -03371-37637 */.
32f20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
32f30 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20  TF16BE        3 
32f40 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39     /* IMP: R-519
32f50 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66  71-34154 */.#def
32f60 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
32f70 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
32f80 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
32f90 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
32fa0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
32fb0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
32fc0 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
32fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32fe0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
32ff0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
33000 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
33010 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
33020 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
33030 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
33040 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
33050 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
33060 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
33070 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
33080 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
33090 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
330a0 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
330b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
330c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
330d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
330e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
330f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
33100 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
33110 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
33120 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
33130 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
33140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
33150 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
33160 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
33170 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
33180 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
33190 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
331a0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
331b0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
331c0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
331d0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
331e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
331f0 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
33200 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
33210 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
33220 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
33230 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
33240 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
33250 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70    To encourage p
33260 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76  rogrammers to av
33270 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  oid.** these fun
33280 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20  ctions, we will 
33290 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74  not explain what
332a0 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
332b0 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
332c0 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
332d0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
332e0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
332f0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
33300 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
33310 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
33320 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
33330 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
33340 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
33350 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
33360 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
33370 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
33380 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
33390 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
333a0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
333b0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
333c0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
333d0 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
333e0 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
333f0 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
33400 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33410 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
33420 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
33430 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
33440 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20  4,int),.        
33450 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
33460 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
33470 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
33480 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
33490 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
334a0 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
334b0 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
334c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
334d0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
334e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
334f0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
33500 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
33510 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
33520 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
33530 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
33540 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
33550 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
33560 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
33570 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
33580 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
33590 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
335a0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
335b0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
335c0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
335d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
335e0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
335f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33600 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
33610 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
33620 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
33630 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
33640 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
33650 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
33660 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
33670 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
33680 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
33690 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
336a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
336b0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
336c0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
336d0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
336e0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
336f0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
33700 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
33710 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
33720 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
33730 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
33740 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33750 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
33760 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
33770 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
33780 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
33790 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
337a0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
337b0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
337c0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
337d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
337e0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
337f0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
33800 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
33810 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
33820 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
33830 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
33840 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
33850 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
33860 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
33870 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
33880 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
33890 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
338a0 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
338b0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
338c0 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
338d0 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
338e0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
338f0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
33900 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
33910 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
33920 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
33930 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
33940 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
33950 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
33960 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
33970 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
33980 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
33990 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
339a0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
339b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
339c0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
339d0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
339e0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
339f0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
33a00 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
33a10 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
33a20 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
33a30 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
33a40 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
33a50 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
33a60 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
33a70 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
33a80 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
33a90 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
33aa0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
33ab0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
33ac0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
33ad0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
33ae0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
33af0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
33b00 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
33b10 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
33b20 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
33b30 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
33b40 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
33b50 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
33b60 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
33b70 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
33b80 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
33b90 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
33ba0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
33bb0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
33bc0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
33bd0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
33be0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
33bf0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
33c00 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
33c10 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
33c20 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
33c30 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
33c40 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
33c50 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
33c60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
33c70 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
33c80 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
33c90 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
33ca0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
33cb0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
33cc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
33cd0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
33ce0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
33cf0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
33d00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
33d10 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
33d20 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
33d30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
33d40 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
33d50 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
33d60 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
33d70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
33d80 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
33d90 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
33da0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
33db0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
33dc0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
33dd0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
33de0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
33df0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
33e00 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
33e10 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
33e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
33e30 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
33e40 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
33e50 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
33e60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
33e70 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
33e80 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
33e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33ea0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
33eb0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
33ec0 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
33ed0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
33ee0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
33ef0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
33f00 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
33f10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
33f20 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
33f30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
33f40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33f50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
33f60 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
33f70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
33f80 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
33f90 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
33fa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
33fb0 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
33fc0 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
33fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
33fe0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
33ff0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
34000 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34010 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49  _context.**.** I
34020 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
34030 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
34040 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
34050 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
34060 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
34070 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
34080 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
34090 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
340a0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
340b0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
340c0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
340d0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
340e0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
340f0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
34100 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
34110 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
34120 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
34130 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
34140 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
34150 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
34160 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
34170 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
34180 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
34190 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
341a0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
341b0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
341c0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
341d0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
341e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
341f0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
34200 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
34210 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
34220 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
34230 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
34240 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
34250 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
34260 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
34270 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
34280 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
34290 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
342a0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
342b0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
342c0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
342d0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
342e0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
342f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
34300 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
34310 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
34320 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
34330 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
34340 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
34350 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34360 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
34370 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
34380 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
34390 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
343a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
343b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
343c0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
343d0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
343e0 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
343f0 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
34400 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
34410 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
34420 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
34430 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
34440 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
34450 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
34460 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
34470 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
34480 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
34490 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
344a0 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
344b0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
344c0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
344d0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
344e0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
344f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
34500 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
34510 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
34520 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
34530 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
34540 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
34550 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
34560 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
34570 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
34580 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
34590 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
345a0 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
345b0 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
345c0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
345d0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
345e0 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
345f0 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
34600 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
34610 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
34620 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
34630 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
34640 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
34650 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34660 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
34670 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
34680 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
34690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
346a0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
346b0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
346c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
346d0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
346e0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
346f0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
34700 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
34710 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
34720 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
34730 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
34740 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
34750 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
34760 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
34770 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
34780 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
34790 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
347a0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
347b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
347c0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
347d0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
347e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
347f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
34800 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
34810 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
34820 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
34830 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
34840 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
34850 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34860 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
34870 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
34880 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
34890 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
348a0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
348b0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
348c0 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
348d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
348e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
348f0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
34900 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34910 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
34920 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
34930 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
34940 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
34950 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34960 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
34970 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
34980 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
34990 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
349a0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
349b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
349c0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
349d0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
349e0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
349f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
34a00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34a10 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
34a20 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
34a30 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
34a40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
34a50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34a60 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
34a70 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
34a80 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
34a90 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
34aa0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
34ab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
34ac0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
34ad0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
34ae0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34af0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
34b00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34b10 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
34b20 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
34b30 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
34b40 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
34b50 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
34b60 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
34b70 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
34b80 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
34b90 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
34ba0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
34bb0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
34bc0 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44  y Data.** METHOD
34bd0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
34be0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  t.**.** These fu
34bf0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
34c00 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72  sed by (non-aggr
34c10 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74  egate) SQL funct
34c20 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
34c30 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
34c40 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
34c50 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
34c60 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
34c70 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
34c80 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
34c90 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
34ca0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
34cb0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
34cc0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
34cd0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
34ce0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
34cf0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
34d00 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a  .  An example.**
34d10 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d   of where this m
34d20 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69  ight be useful i
34d30 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65  s in a regular-e
34d40 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
34d50 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ng.** function. 
34d60 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
34d70 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
34d80 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
34d90 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a  an be stored as.
34da0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
34db0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
34dc0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20  pattern string. 
34dd0 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e   .** Then as lon
34de0 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e  g as the pattern
34df0 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20   string remains 
34e00 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65  the same,.** the
34e10 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
34e20 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
34e30 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
34e40 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
34e50 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
34e60 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
34e70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
34e80 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
34e90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
34ea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
34eb0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
34ec0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
34ed0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34ee0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
34ef0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
34f00 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
34f10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34f20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
34f30 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
34f40 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
34f50 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
34f60 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
34f70 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33  nt, this sqlite3
34f80 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
34f90 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
34fa0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
34fb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
34fc0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34fd0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65  ta(C,N,P,X) inte
34fe0 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73  rface saves P as
34ff0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
35000 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
35010 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
35020 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35030 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71  nction.  ^Subseq
35040 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
35050 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
35060 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e  data(C,N) return
35070 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74   P from the most
35080 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74   recent.** sqlit
35090 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
350a0 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20  ,N,P,X) call if 
350b0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
350c0 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a  still valid or.*
350d0 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65  * NULL if the me
350e0 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
350f0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41  discarded..** ^A
35100 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74  fter each call t
35110 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
35120 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77  xdata(C,N,P,X) w
35130 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55  here X is not NU
35140 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  LL,.** SQLite wi
35150 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
35160 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
35170 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74  n X with paramet
35180 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20  er P exactly.** 
35190 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d  once, when the m
351a0 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61  etadata is disca
351b0 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  rded..** SQLite 
351c0 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61  is free to disca
351d0 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  rd the metadata 
351e0 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63  at any time, inc
351f0 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20  luding: <ul>.** 
35200 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f  <li> when the co
35210 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
35220 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
35230 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c  hanges, or.** <l
35240 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  i> when [sqlite3
35250 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
35260 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
35270 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  ] is called for 
35280 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20  the.**      SQL 
35290 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a  statement, or.**
352a0 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74   <li> when sqlit
352b0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
352c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69   is invoked agai
352d0 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61  n on the same pa
352e0 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c  rameter, or.** <
352f0 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f  li> during the o
35300 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f  riginal sqlite3_
35310 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61  set_auxdata() ca
35320 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79  ll when a memory
35330 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61   .**      alloca
35340 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
35350 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  s. </ul>)^.**.**
35360 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62   Note the last b
35370 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75  ullet in particu
35380 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75  lar.  The destru
35390 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71  ctor X in .** sq
353a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
353b0 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74  a(C,N,P,X) might
353c0 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64   be called immed
353d0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
353e0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  he.** sqlite3_se
353f0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
35400 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72  rface even retur
35410 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74  ns.  Hence sqlit
35420 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
35430 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61  .** should be ca
35440 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e  lled near the en
35450 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  d of the functio
35460 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
35470 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63   and the.** func
35480 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
35490 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d  ion should not m
354a0 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50  ake any use of P
354b0 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65   after.** sqlite
354c0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
354d0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  has been called.
354e0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
354f0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
35500 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
35510 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
35520 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ls for.** functi
35530 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  on parameters th
35540 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74  at are compile-t
35550 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69  ime constants, i
35560 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c  ncluding literal
35570 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
35580 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20  parameters] and 
35590 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70  expressions comp
355a0 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  osed from the sa
355b0 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  me.)^.**.** Thes
355c0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
355d0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
355e0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
355f0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
35600 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
35610 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
35620 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
35630 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
35640 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
35650 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
35660 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
35670 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
35680 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
35690 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
356a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
356b0 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
356c0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
356d0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
356e0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
356f0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
35700 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
35710 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
35720 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
35730 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
35740 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
35750 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
35760 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
35770 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
35780 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
35790 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
357a0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
357b0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
357c0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
357d0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
357e0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
357f0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
35800 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
35810 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
35820 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
35830 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
35840 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
35850 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
35860 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
35870 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
35880 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
35890 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
358a0 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
358b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
358c0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
358d0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
358e0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
358f0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
35900 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
35910 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
35920 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
35930 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
35940 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
35950 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
35960 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
35970 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
35980 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
35990 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
359a0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
359b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
359c0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
359d0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
359e0 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  on.** METHOD: sq
359f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
35a00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
35a10 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
35a20 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
35a30 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
35a40 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
35a50 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
35a60 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
35a70 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
35a80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
35a90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
35aa0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
35ab0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
35ac0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
35ad0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
35ae0 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
35af0 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
35b00 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
35b10 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
35b20 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
35b30 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
35b40 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
35b50 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
35b60 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
35b70 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
35b80 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
35b90 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
35ba0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
35bb0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
35bc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35bd0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
35be0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
35bf0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
35c00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35c10 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
35c20 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
35c30 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
35c40 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
35c50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
35c60 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
35c70 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
35c80 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
35c90 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
35ca0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35cb0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
35cc0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
35cd0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
35ce0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35cf0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35d00 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
35d10 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
35d20 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
35d30 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
35d40 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
35d50 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
35d60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
35d70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35d80 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
35d90 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
35da0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
35db0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
35dc0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35dd0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
35de0 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
35df0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
35e00 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
35e10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35e20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
35e30 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
35e40 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
35e50 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
35e60 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
35e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
35e80 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
35e90 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
35ea0 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
35eb0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
35ec0 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
35ed0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
35ee0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
35ef0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35f00 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
35f10 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
35f20 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
35f30 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
35f40 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
35f50 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
35f60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35f70 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
35f80 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
35f90 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
35fa0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
35fb0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35fc0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
35fd0 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
35fe0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
35ff0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
36000 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36010 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
36020 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36030 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
36040 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
36050 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
36060 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
36070 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
36080 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
36090 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
360a0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
360b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
360c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
360d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
360e0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
360f0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
36100 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
36110 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
36120 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
36130 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
36140 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
36150 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
36160 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36170 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
36180 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
36190 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
361a0 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
361b0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
361c0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
361d0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
361e0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
361f0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
36200 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
36210 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
36220 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
36230 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
36240 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
36250 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36260 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
36270 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
36280 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
36290 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
362a0 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
362b0 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
362c0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
362d0 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
362e0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
362f0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
36300 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
36310 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
36320 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
36330 2a 2a 20 6f 72 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 72  sult_error16() r
36350 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
36360 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
36370 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
36380 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36390 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
363a0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
363b0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
363c0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
363d0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
363e0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
363f0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
36400 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
36410 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36420 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
36430 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
36440 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
36450 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
36460 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
36470 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
36480 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
36490 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
364a0 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
364b0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
364c0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
364d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
364e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
364f0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
36500 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
36510 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
36520 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
36530 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
36540 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
36550 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
36560 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
36570 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
36580 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36590 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
365a0 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
365b0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
365c0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
365d0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
365e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
365f0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
36600 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
36610 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
36620 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
36630 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36640 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
36650 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36660 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
36670 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
36680 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
36690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
366a0 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
366b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
366c0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
366d0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
366e0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
366f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36700 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36710 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
36720 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
36730 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
36740 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
36750 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
36760 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
36770 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
36780 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
36790 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
367a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
367b0 6c 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65  lt_text64() inte
367c0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
367d0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61  eturn value of a
367e0 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
367f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36800 6e 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73  n to be a text s
36810 74 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f  tring in an enco
36820 64 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65  ding.** specifie
36830 64 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28  d by the fifth (
36840 61 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65  and last) parame
36850 74 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20  ter, which must 
36860 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51  be one.** of [SQ
36870 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
36880 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
36890 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
368a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
368b0 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  ]..** ^SQLite ta
368c0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
368d0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
368e0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
368f0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
36900 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
36910 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
36920 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
36930 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
36940 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
36950 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
36960 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
36970 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
36980 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
36990 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
369a0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
369b0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
369c0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
369d0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
369e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
369f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
36a00 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
36a10 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
36a20 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
36a30 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
36a40 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
36a50 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
36a60 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
36a70 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
36a80 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
36a90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36aa0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
36ab0 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64  ult.  If the 3rd
36ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
36ad0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
36ae0 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74   it.** must be t
36af0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69  he byte offset i
36b00 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77  nto the string w
36b10 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
36b20 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a  minator would.**
36b30 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73   appear if the s
36b40 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20  tring where NUL 
36b50 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
36b60 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
36b70 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  rs occur.** in t
36b80 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62  he string at a b
36b90 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20  yte offset that 
36ba0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  is less than the
36bb0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72   value of the 3r
36bc0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20  d.** parameter, 
36bd0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
36be0 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63  ng string will c
36bf0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
36c00 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  NULs and the.** 
36c10 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
36c20 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20  sions operating 
36c30 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20  on strings with 
36c40 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
36c50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
36c60 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
36c70 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
36c80 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
36c90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
36ca0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
36cb0 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
36cc0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
36cd0 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
36ce0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
36cf0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
36d00 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
36d10 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
36d20 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
36d30 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
36d40 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
36d50 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
36d60 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
36d70 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
36d80 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
36d90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36da0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
36db0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
36dc0 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
36dd0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
36de0 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
36df0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
36e00 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
36e10 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
36e20 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
36e30 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
36e40 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
36e50 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
36e60 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
36e70 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
36e80 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
36e90 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
36ea0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
36eb0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
36ec0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36ed0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
36ee0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36ef0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
36f00 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
36f10 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
36f20 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
36f30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
36f40 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
36f50 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
36f60 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
36f70 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
36f80 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
36f90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36fa0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
36fb0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
36fc0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
36fd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36fe0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
36ff0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
37000 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
37010 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37020 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
37030 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
37040 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
37050 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
37060 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
37070 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
37080 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
37090 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
370a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
370b0 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
370c0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
370d0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
370e0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
370f0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
37100 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
37110 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
37120 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
37130 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
37140 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
37150 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
37160 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
37170 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
37180 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
37190 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
371a0 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
371b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
371c0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
371d0 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
371e0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
371f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
37200 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
37210 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
37220 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
37230 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
37240 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
37250 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37260 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
37270 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
37280 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
37290 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
372a0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
372b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
372c0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
372d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
372e0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
372f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
37300 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37310 6c 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  lt_blob64(sqlite
37320 33 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74  3_context*,const
37330 20 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20   void*,.        
37340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37350 20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36     sqlite3_uint6
37360 34 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  4,void(*)(void*)
37370 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37380 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
37390 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
373a0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
373b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
373c0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
373d0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
373e0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
373f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37400 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
37410 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
37420 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
37430 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37440 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
37450 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
37460 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37470 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
37480 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
37490 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
374a0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
374b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
374c0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
374d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
374e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
374f0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
37500 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
37510 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37520 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
37530 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37540 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
37550 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
37560 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37570 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
37580 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37590 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
375a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
375b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
375c0 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f  _text64(sqlite3_
375d0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
375e0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
375f0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
37600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37610 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
37620 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
37630 6e 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73  ncoding);.void s
37640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37650 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
37660 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
37670 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
37680 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
37690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
376a0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
376b0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
376c0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
376d0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
376e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
376f0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
37700 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37710 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
37720 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37730 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37740 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
37750 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
37760 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
37770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
37780 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
37790 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
377a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
377b0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
377c0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
377d0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
377e0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
377f0 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
37800 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
37810 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
37820 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
37830 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
37840 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
37850 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
37860 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
37870 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
37880 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
37890 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
378a0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
378b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
378c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
378d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
378e0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
378f0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
37900 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
37910 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
37920 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
37930 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
37940 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
37950 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
37960 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
37970 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
37980 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
37990 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
379a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
379b0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
379c0 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
379d0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
379e0 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
379f0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
37a00 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
37a10 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
37a20 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
37a30 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
37a40 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
37a50 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
37a60 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
37a70 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
37a80 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
37a90 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
37aa0 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
37ab0 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
37ac0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
37ad0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37ae0 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
37af0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
37b00 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
37b10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
37b20 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
37b30 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
37b40 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
37b50 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
37b60 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
37b70 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
37b80 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
37b90 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
37ba0 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
37bb0 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
37bc0 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
37bd0 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
37be0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
37bf0 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
37c00 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
37c10 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
37c20 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
37c30 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
37c40 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
37c50 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37c60 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
37c70 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
37c80 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
37c90 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
37ca0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
37cb0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
37cc0 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
37cd0 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
37ce0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
37cf0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
37d00 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
37d10 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
37d20 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
37d30 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
37d40 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
37d50 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
37d60 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
37d70 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
37d80 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
37d90 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
37da0 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
37db0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
37dc0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
37dd0 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
37de0 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
37df0 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
37e00 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
37e10 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
37e20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
37e30 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
37e40 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
37e50 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
37e60 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
37e70 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
37e80 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
37e90 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
37ea0 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
37eb0 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
37ec0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
37ed0 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
37ee0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
37ef0 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
37f00 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
37f10 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
37f20 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
37f30 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
37f40 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
37f50 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
37f60 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
37f70 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
37f80 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
37f90 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
37fa0 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
37fb0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
37fc0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
37fd0 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
37fe0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
37ff0 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
38000 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
38010 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
38020 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
38030 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
38040 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
38050 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
38060 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
38070 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
38080 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
38090 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
380a0 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
380b0 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
380c0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
380d0 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
380e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
380f0 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
38100 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
38110 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
38120 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
38130 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
38140 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
38150 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
38160 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
38170 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
38180 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
38190 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
381a0 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
381b0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
381c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
381d0 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
381e0 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
381f0 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
38200 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
38210 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
38220 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
38230 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
38240 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
38250 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
38260 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
38270 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
38280 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
38290 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
382a0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
382b0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
382c0 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
382d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
382e0 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
382f0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
38300 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
38310 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
38320 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
38330 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
38340 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
38350 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
38360 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
38370 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
38380 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
38390 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
383a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
383b0 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
383c0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
383d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
383e0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
383f0 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
38400 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
38410 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
38420 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
38430 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
38440 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
38450 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
38460 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
38470 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
38480 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
38490 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
384a0 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
384b0 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
384c0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
384d0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
384e0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
384f0 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
38500 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
38510 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
38520 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
38530 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
38540 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
38550 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
38560 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
38570 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
38580 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
38590 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
385a0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
385b0 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
385c0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
385d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
385e0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
385f0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
38600 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
38610 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
38620 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
38630 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
38640 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
38650 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
38660 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
38670 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
38680 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
38690 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
386a0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
386b0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
386c0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
386d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
386e0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
386f0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
38700 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
38710 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
38720 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
38730 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
38740 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
38750 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
38760 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
38770 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
38780 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
38790 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
387a0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
387b0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
387c0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
387d0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
387e0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
387f0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
38800 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
38810 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38820 46 3a 20 43